From 487e07aea630376cb5419d21fa4a3a942b2fe2c2 Mon Sep 17 00:00:00 2001
From: zYne <zYne@625475ce-881a-0410-a577-b389adb331d8>
Date: Fri, 29 Sep 2006 11:17:16 +0000
Subject: [PATCH] added DQL introduction

---
 ...octrine Query Language) - Introduction.php | 26 +++++++++++++++++++
 ...octrine Query Language) - Introduction.php | 19 ++++++++++++++
 manual/documentation.php                      |  5 +++-
 manual/styles/basic.css                       |  3 +++
 4 files changed, 52 insertions(+), 1 deletion(-)
 create mode 100644 manual/codes/DQL (Doctrine Query Language) - Introduction.php
 create mode 100644 manual/docs/DQL (Doctrine Query Language) - Introduction.php

diff --git a/manual/codes/DQL (Doctrine Query Language) - Introduction.php b/manual/codes/DQL (Doctrine Query Language) - Introduction.php
new file mode 100644
index 000000000..223c0a623
--- /dev/null
+++ b/manual/codes/DQL (Doctrine Query Language) - Introduction.php	
@@ -0,0 +1,26 @@
+<?php
+// DO NOT USE THE FOLLOWING CODE 
+// (using many sql queries for object population):
+
+$users = $conn->getTable('User')->findAll();
+
+foreach($users as $user) {
+    print $user->name."<br \>";
+    foreach($user->Phonenumber as $phonenumber) {
+        print $phonenumber."<br \>";
+    }
+}
+
+// same thing implemented much more efficiently: 
+// (using only one sql query for object population)
+
+$users = $conn->query("FROM User.Phonenumber");
+
+foreach($users as $user) {
+    print $user->name."<br \>";
+    foreach($user->Phonenumber as $phonenumber) {
+        print $phonenumber."<br \>";
+    }
+}
+
+?>
diff --git a/manual/docs/DQL (Doctrine Query Language) - Introduction.php b/manual/docs/DQL (Doctrine Query Language) - Introduction.php
new file mode 100644
index 000000000..578aee195
--- /dev/null
+++ b/manual/docs/DQL (Doctrine Query Language) - Introduction.php	
@@ -0,0 +1,19 @@
+Doctrine Query Language(DQL) is an Object Query Language created for helping users in complex object retrieval.
+You should always consider using DQL(or raw SQL) when retrieving relational data efficiently (eg. when fetching users and their phonenumbers).
+<br \><br \>
+When compared to using raw SQL, DQL has several benefits: <br \>
+    <ul>
+    <li \>From the start it has been designed to retrieve records(objects) not result set rows
+    </ul>
+    <ul>
+    <li \>DQL understands relations so you don't have to type manually sql joins and join conditions
+    </ul>
+    <ul>
+    <li \>DQL has some very complex built-in algorithms like (the record limit algorithm) which can help
+    developer to efficiently retrieve objects
+    </ul>
+    <ul>
+    <li \>It supports some many functions that help dealing with one-to-many, many-to-many relational data with conditional fetching.
+    </ul>
+
+If the power of DQL isn't enough, you should consider using the rawSql API for object population.
diff --git a/manual/documentation.php b/manual/documentation.php
index ed28144a7..8f56dfff9 100644
--- a/manual/documentation.php
+++ b/manual/documentation.php
@@ -298,7 +298,10 @@ $menu = array("Getting started" =>
                         */
                     ),
            "DQL (Doctrine Query Language)" =>
-                            array('Syntax' =>
+
+                            array('Introduction', 
+                                  'Syntax' =>
+
                                   array(
                                         'FROM',
                                         'WHERE',
diff --git a/manual/styles/basic.css b/manual/styles/basic.css
index f3170e566..a9ad74b05 100644
--- a/manual/styles/basic.css
+++ b/manual/styles/basic.css
@@ -42,6 +42,9 @@ color: #367FAC;
 a.big {
 font-size: 14 px;
 }
+i {
+color: #367FAC;
+}
 a {
 color: #367FAC;
 }