From 35626a65931342d6cc8e35f2582f9a8758f08236 Mon Sep 17 00:00:00 2001
From: Ralf Becker <ralfbecker@outdoor-training.de>
Date: Mon, 17 Aug 2009 12:28:30 +0000
Subject: [PATCH] "docu update to avoid a common pitfall"

---
 etemplate/inc/class.so_sql.inc.php | 36 +++++++++++++++++++++++-------
 1 file changed, 28 insertions(+), 8 deletions(-)

diff --git a/etemplate/inc/class.so_sql.inc.php b/etemplate/inc/class.so_sql.inc.php
index a4e49d93d5..0e8197d741 100644
--- a/etemplate/inc/class.so_sql.inc.php
+++ b/etemplate/inc/class.so_sql.inc.php
@@ -287,10 +287,22 @@ class so_sql
 	 * changes the data from the db-format to your work-format
 	 *
 	 * It gets called everytime when data is read from the db.
-	 * This default implementation only converts the timestamps mentioned in $this->timestampfs from server to user time.
-	 * You can reimplement it in a derived class
+	 * This default implementation only converts the timestamps mentioned in $this->timestamps from server to user time.
+	 * You can reimplement it in a derived class like this:
+	 *
+	 * function db2data($data=null)
+	 * {
+	 * 		if (($intern = !is_array($data)))
+	 * 		{
+	 * 			$data =& $this->data;
+	 * 		}
+	 * 		// do your own modifications here
+	 *
+	 * 		return parent::db2data($intern ? null : $data);	// important to use null, if $intern!
+	 * }
 	 *
 	 * @param array $data=null if given works on that array and returns result, else works on internal data-array
+	 * @return array
 	 */
 	function db2data($data=null)
 	{
@@ -315,8 +327,6 @@ class so_sql
 				}
 			}
 		}
-		// do the necessare changes here
-
 		return $data;
 	}
 
@@ -325,13 +335,25 @@ class so_sql
 	 *
 	 * It gets called everytime when data gets writen into db or on keys for db-searches.
 	 * This default implementation only converts the timestamps mentioned in $this->timestampfs from user to server time.
-	 * You can reimplement it in a derived class
+	 * You can reimplement it in a derived class like this:
+	 *
+	 * function data2db($data=null)
+	 * {
+	 * 		if (($intern = !is_array($data)))
+	 * 		{
+	 * 			$data =& $this->data;
+	 * 		}
+	 * 		// do your own modifications here
+	 *
+	 * 		return parent::data2db($intern ? null : $data);	// important to use null, if $intern!
+	 * }
 	 *
 	 * @param array $data=null if given works on that array and returns result, else works on internal data-array
+	 * @return array
 	 */
 	function data2db($data=null)
 	{
-		if ($intern = !is_array($data))
+		if (!is_array($data))
 		{
 			$data = &$this->data;
 		}
@@ -352,8 +374,6 @@ class so_sql
 				}
 			}
 		}
-		// do the necessary changes here
-
 		return $data;
 	}