From a76fe6eca673d1fcb2891e7fc3534ec4b7a7686c Mon Sep 17 00:00:00 2001
From: hickert <hickert@594d385d-05f5-0310-b6e9-bd551577e9d8>
Date: Mon, 27 Sep 2010 13:30:25 +0000
Subject: [PATCH] Added comments

git-svn-id: https://oss.gonicus.de/repositories/gosa/trunk@19802 594d385d-05f5-0310-b6e9-bd551577e9d8
---
 .../goto/Config/class_DeviceConfig.inc        |   3 +-
 .../goto/Config/class_TemplateEngine.inc      | 102 ++++++++++++------
 2 files changed, 72 insertions(+), 33 deletions(-)

diff --git a/gosa-plugins/goto/admin/systems/goto/Config/class_DeviceConfig.inc b/gosa-plugins/goto/admin/systems/goto/Config/class_DeviceConfig.inc
index 4b519b2bf..a40c864a1 100644
--- a/gosa-plugins/goto/admin/systems/goto/Config/class_DeviceConfig.inc
+++ b/gosa-plugins/goto/admin/systems/goto/Config/class_DeviceConfig.inc
@@ -192,8 +192,7 @@ class DeviceConfig extends plugin
 
         // Update the template engine to use another type of item and 
         //  some other values.
-        $this->TemplateEngine->setType($this->currentItemType);
-        $this->TemplateEngine->setValues($this->currentItem['values']);
+        $this->TemplateEngine->setValues($this->currentItemType,$this->currentItem['values']);
     }
 
 
diff --git a/gosa-plugins/goto/admin/systems/goto/Config/class_TemplateEngine.inc b/gosa-plugins/goto/admin/systems/goto/Config/class_TemplateEngine.inc
index 3ef186298..fb4d55a76 100644
--- a/gosa-plugins/goto/admin/systems/goto/Config/class_TemplateEngine.inc
+++ b/gosa-plugins/goto/admin/systems/goto/Config/class_TemplateEngine.inc
@@ -1,79 +1,116 @@
 <?php
 
+/*! \brief  A template engine used to render dynamic template
+ *           for the GOsa-devices.
+ */
 class TemplateEngine
 {
     private $config;
     private $data = array();    
     private $template = "";
-
     private $itemType = '';
     private $widgets = array();
 
+
+    /*! \brief  Constructs the template engine. 
+     *  @param  Config  The GOsa configuration object.
+     */
     function __construct($config)
     {
         $this->config = &$config;
     }
 
-    function setValues($values)
+
+    /*! \brief  Load/Sets the instruction-set to use for the current
+     *           device configuration.
+     *          A device configruation tells us what options 
+     *           an item can have and what children.
+     *  @param  Array   The instruction set to use.
+     */
+    function load($array)
     {
-        foreach($values as $name => $value){
-            if(!isset($this->widgets[$name])){
-                $class = get_class();
-                echo "Unknown option '{$name}' for {$class}!)}<br>";
-                 continue;
-            }
-            $this->widgets[$name]->setValue($value);
-        }
+        $this->data = $array;
+    }
+
+
+    /*! \brief  Set the template which will be used to generate 
+     *           the HTML content for this configuration session.
+     *  @param  String  A template filename.
+     */
+    function setTemplate($tmpl)
+    {
+        $this->template = $tmpl;
     }
 
-    function setType($name)
+
+    /*! \brief  Returns the list of widgets which are currently used 
+     *           by the template engine to render the plugin.
+     *  @return Array  A list of widgets.
+     */
+    function getWidgets()
+    {
+        return($this->widgets);
+    }     
+
+
+    /*! \brief  Sets the current item type we want to render
+     *          E.g.  'KickstartTemplate' and the corresponding values.
+     *
+     *  @param  String  The name of the item we want to render now.
+     *  @param  Array   The initial value.
+     */
+    function setValues($name)
     {
+        // Set the current item type and reset the widget list.
         $this->itemType = $name;
         $this->widgets = array();
 
+        // Do nothing if something seems to be wrong. 
         if(!isset($this->data[$this->itemType])){
             echo "Undefined item type '{$name}'!<br>";
             return;
         }
+
+        // Get the options provided by the item and create widget for them.
         $data = $this->data[$this->itemType];
         if(isset($data['options']) && count($data['options'])){
             foreach($data['options'] as $name => $item){
-
                 $widgetClassName = "TemplateWidget_{$item['type']}";
+
+                // Check if the widget is available, if it is not, use a default (string).
                 if(!class_available($widgetClassName)){
                     echo "Unknown widget class {$widgetClassName}! Falling back to default widget.<br>";
                     $widgetClassName = "TemplateWidget_string";
                 }
 
+                // Prepare the value for the widget 
+                $value = $item['value'];
+                if(isset($values[$name])){
+                    $value = $values[$name];
+                }
+
+                // Create the new widget.
                 $this->widgets[$name] = new $widgetClassName($this->config, $name, 
-                    $item['value'],
-                    $item['description'],
-                    $item['required'],
-                    $item['type'],
-                    $item['display']);
+                        $item['value'],
+                        $item['description'],
+                        $item['required'],
+                        $item['type'],
+                        $item['display']);
             }
         }
     }
 
-    function load($array)
-    {
-        $this->data = $array;
-    }
-  
-    function setTemplate($tmpl)
-    {
-        $this->template = $tmpl;
-    }
-    
-    function getWidgets()
-    {
-        return($this->widgets);
-    }     
 
+    /*! \brief  Creates the HTML content for the given list of widgets
+     *  @return String  The HTML content.
+     */
     function render()
     {
         $smarty = get_smarty();
         $smarty->assign("type", $this->itemType);
+
+        // Tell smarty the HTML-content for each widget and the name that should be
+        //  displayed.
         foreach($this->widgets as $widget){
             $smarty->assign($widget->getName(), $widget->render());
             $smarty->assign($widget->getName()."Name", $widget->getDisplayName());
@@ -81,6 +118,9 @@ class TemplateEngine
         return($smarty->fetch(get_template_path("goto/Config/{$this->template}", TRUE)));
     }
 
+
+    /*! \brief  Keep track of posted values.
+     */
     function save_object()
     {
         foreach($this->widgets as $widget){
-- 
2.30.2