Added comments to multi edit handler.

git-svn-id: https://oss.gonicus.de/repositories/gosa/trunk@8054 594d385d-05f5-0310-b6e9-bd551577e9d8

diff --git a/include/class_multi_plug.inc b/include/class_multi_plug.inc
index e8a16cc751ebe65d6917f688dda17a63fef2b268..17cdaa73e1423edfb9a440fb6a8c571a4ad5be2f 100644 (file)
--- a/include/class_multi_plug.inc
+++ b/include/class_multi_plug.inc
@@ -1,5 +1,46 @@
 <?php
-
+/*
+   This code is part of GOsa (https://oss.gonicus.de/labs/gosa/)
+   Copyright (C) 2007 Fabian Hickert
+
+   This program is free software; you can redistribute it and/or modify
+   it under the terms of the GNU General Public License as published by
+   the Free Software Foundation; either version 2 of the License, or
+   (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program; if not, write to the Free Software
+   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+ */
+
+/*
+
+Data structure :  
+  
+  |->o_tab                      <-- dummy object that will be displayed displayed 
+  |->a_handles                  <-- tab object for each given dn
+     |->tab object for dn 1 
+     |->tab object for dn 2
+      ...
+     |->tab object for dn n
+*/
+
+
+/*! \brief   Handles multiple edits for a given set of dns.
+    \author  Fabian Hickert
+    \version 1.01
+    \date    2007/12/07
+
+    This class edits multiple tab objects at once. 
+    1. There is a dummy tab object initialized that collects the user input.
+    2. All given objects specified by '$dn' will be initialized and the collected
+     data from the dummy object will be populated to them.
+ */
 class multi_plug
 {
   /* Tab handler for each given dn entry */
@@ -8,67 +49,118 @@ class multi_plug
   /* Dummy handler which collects the data */
   private $o_tab     = NULL;  
 
-  public $dn    = array();
-  public $config = NULL;
-  private $s_class  = "";
+  public $dn      = array();
+  public $config  = NULL;
+  private $s_class= "";
   public $current = "";
 
+  /*! \brief    Creates a multi_plug object
+     @param   object  $config GOsa Configuration object
+     @param   string  $class  The class name of the tab we want to edit. e.g. usertabs
+     @param   string  $tab    The config tab name e.g. USERTABS 
+     @param   array   $dns    The object dns we want to edit.
+     @return  object  multi_plug
+   */
   public function __construct($config,$class,$tab,$dns)
   {
-    $this->dn = $dns;
-    $this->config = $config;
-    $this->s_class = $class;
-    $this->o_tab = new $class($config,$tab,"new");
+    $this->dn       = $dns;
+    $this->config   = $config;
+    $this->s_class  = $class;
+
+    /* Initialize collector object 
+     * Used to display the ui and to collect the user input.
+     */
+    $this->o_tab    = new $class($config,$tab,"new");
 
+    /* Check if the specified tab object supports multiple edits 
+     */
     if($this->o_tab->multiple_support_available()){
+
+      /* Enable multiple actions for the collector object 
+       */ 
       $this->o_tab->enable_multiple_support();
-    
+
+      /* Initialize the objects we want to edit at once 
+       */
       foreach($dns as $dn){
         $this->a_handles[] = new $class($config,$tab,$dn);
       }
     }
   }
 
+  /*! \brief    Returns the edit ui for multiple edit.
+     @return    string  HTML User interface for given tab object.
+   */
   public function execute()
   {
     return($this->o_tab->execute());
   }
 
+
+  /*! \brief    Checks if one of the objects we want to edit is locked. 
+     @return    boolean   Returns TRUE if at least one entry is locked, else false.
+   */
   public function entries_locked()
   {
     return(FALSE);
   }
 
+
+  /*! \brief    Generates a lock message that can be displayed if an entry is locked.
+     @return    string  Returns a list of locked entries 
+   */
   public function display_lock_message()
   {
     return("sdf");
   }
 
+
+  /*! \brief    Locks all currently managed objects (array $this->dn) 
+     @return    boolean   Returns TRUE
+   */
   public function lock_entries($uid)
   {
     return(TRUE);
   }
 
+
+  /*! \brief    Checks if the given tab object supports multiple edit.
+     @return    boolean   Returns TRUE if the given tab objects supports multiple edit else FALSE.
+   */
   public function multiple_available()
   {
     return($this->o_tab->multiple_support_available());
   }
 
+
+  /*! \brief    Sets the currently active tab. The tab that will be displayed by $this->execute(). 
+   */
   public function set_active_tab($str)
   {
     $this->current = $str;
   }
 
+
+  /*! \brief    Returns the object info string, that can be displayed in the tab header.
+      @return   string  Returns an information string, containing the list of currently edited dns.
+   */
   public function get_object_info()
   {
     return("Oi -----");
   }
 
+
+  /*! \brief    Handles all HTML posts from the dummy tab object. 
+   */
   public function save_object()
   {
     $this->o_tab->save_object(); 
   }
 
+
+  /*! \brief    Checks if the values fetched by $this->save_object() are valid.
+      @param    array Returns an array containig all error messages.
+   */
   public function check()
   {
     $this->populate_values();
@@ -82,11 +174,18 @@ class multi_plug
     return($messages);
   }
 
+
+  /*! \brief    Currently not implemented, later be used to trigger password changes. 
+      @param    boolean Returns TRUE if a password change is needed.
+   */
   public function password_change_needed()
   {
     return(FALSE);
   }
 
+
+  /*! \brief    Populate all collected values to the target tab objects ($this->o_handles)
+   */
   public function populate_values()
   {
 
@@ -102,6 +201,9 @@ class multi_plug
     }
   }
 
+
+  /*! \brief    Save all edited tab objects ($this->o_handles). 
+   */
   public function save()
   {
     if($this->multiple_available() && is_array($this->a_handles)){