[libgda] Added documentation for GdaData.Record class.

[Daniel Espinosa Ortiz <despinosa src gnome org>]

commit 9bd05263875aeeff5e15ad709e1e17c8ca92fbd2
Author: Daniel Espinosa <despinosa src gnome org>
Date:   Mon Mar 26 17:45:05 2012 -0600

    Added documentation for GdaData.Record class.

 doc/mallard/gda-data/Classes.page                |   27 +++++
 doc/mallard/gda-data/Interfaces.page             |   24 +++++
 doc/mallard/gda-data/Record-Class.page           |  112 ++++++++++++++++++++++
 doc/mallard/gda-data/enable-vala-extensions.page |   27 +++++
 doc/mallard/gda-data/index.page                  |   27 +++++
 5 files changed, 217 insertions(+), 0 deletions(-)
---
diff --git a/doc/mallard/gda-data/Classes.page b/doc/mallard/gda-data/Classes.page
new file mode 100644
index 0000000..8d667fa
--- /dev/null
+++ b/doc/mallard/gda-data/Classes.page
@@ -0,0 +1,27 @@
+<page xmlns="http://projectmallard.org/1.0/";
+	 type="topic" id="classes">
+
+  <info>
+    <revision pkgversion="5.2" version="0.1" date="2012-01-18" status="incomplete" />
+    <credit type="author">
+      <name>Daniel Espinosa</name>
+      <email>despinosa src gnome org</email>
+    </credit>
+    <license>
+      <p>Creative Commons Share Alike 3.0</p>
+    </license>
+    <link type="topic" xref="index" />
+  </info>
+
+  <title>
+    Classes
+  </title>
+  <p>
+  GDA's Vala Extensions classes are instantiable. They implement generic interfaces. Use GDA's Vala bindings to get access to database's data. 
+  </p>
+  <p>
+  They load in memory all required data from database when <code>update()</code> method is called; but you are able to set data without call it and then use <code>save()</code> method to set it to the database. Methods <code>update()</code> and <code>save()</code> execute SQL commands directly using GDA's database providers.
+  </p>
+  <p>
+  </p>
+</page>
diff --git a/doc/mallard/gda-data/Interfaces.page b/doc/mallard/gda-data/Interfaces.page
new file mode 100644
index 0000000..c3bc76b
--- /dev/null
+++ b/doc/mallard/gda-data/Interfaces.page
@@ -0,0 +1,24 @@
+<page xmlns="http://projectmallard.org/1.0/";
+	 type="topic" id="interfaces">
+
+  <info>
+    <revision pkgversion="5.2" version="0.1" date="2012-01-18" status="incomplete" />
+    <credit type="author">
+      <name>Daniel Espinosa</name>
+      <email>despinosa src gnome org</email>
+    </credit>
+    <license>
+      <p>Creative Commons Share Alike 3.0</p>
+    </license>
+    <link type="topic" xref="index" />
+  </info>
+
+  <title>
+    Interfaces
+  </title>
+  <p>
+  
+  </p>
+  <p>
+  </p>
+</page>
diff --git a/doc/mallard/gda-data/Record-Class.page b/doc/mallard/gda-data/Record-Class.page
new file mode 100644
index 0000000..8ddf59c
--- /dev/null
+++ b/doc/mallard/gda-data/Record-Class.page
@@ -0,0 +1,112 @@
+<page xmlns="http://projectmallard.org/1.0/";
+	 type="topic" id="record-class">
+
+  <info>
+    <revision pkgversion="5.2" version="0.1" date="2012-01-18" status="incomplete" />
+    <credit type="author">
+      <name>Daniel Espinosa</name>
+      <email>despinosa src gnome org</email>
+    </credit>
+    <license>
+      <p>Creative Commons Share Alike 3.0</p>
+    </license>
+    <link type="topic" xref="classes" />
+  </info>
+
+  <title>
+    Record class
+  </title>
+  <p>
+  <code>Record</code> class is an implementation of <code>DbRecord</code> interface. It uses GDA to get access to a database's row in a table.
+  </p>
+  <p>
+  In order to load data, you need to set a table and a key. Then <code>update()</code> method execute a SELECT command using the key to find the required row in the table.
+  </p>
+  <section id="record-update">
+  <title>Using a Record class to access a row in a table</title>
+  <listing>
+  <desc>
+  This codes initiate a Record class, set a table to use, a key and a connection in order to call update()
+  </desc>
+  <code mime="text/x-c++src">
+  var r = new Record ();
+  var t = new Table ();
+  t.name = "customer";
+  r.table = t;
+  r.connection = connection;
+  r.set_key_value ("id", 1);
+  r.update ();
+  </code>
+  </listing>
+  <p>In the above code, connection is opened before to be set to <code>Record.connection</code> property. You need to setup a <code>Table</code> class to set to <code>Record.table</code> property, but just set <code>Table.name</code> property to the table's name is required. Use <code>Record.set_key_value()</code> method to set the value to the column used in the table as the primary key and to allow <code>update()</code> method to find the correct row (the WHERE clause in SELECT statement), if more than one key exists you must set it; you must know the column and type of value to set.
+  </p>
+  </section>
+  <section id="record-save">
+  <title>Using a Record class to add a new row in a table</title>
+  <listing>
+  <desc>This record setup a row to be added to a database's table</desc>
+  <code mime="text/x-c++src">
+  var r = new Record ();
+  var t = new Table ();
+  t.name = "customer";
+  r.table = t;
+  r.connection = connection;
+  r.set_field_value ("name", "Clausse Rayman");
+  r.set_field_value ("company", "Packing Sources, Ltd.");
+  r.save ();
+  </code>
+  </listing>
+  <p>
+  In the above code a new row will be added. Create a new <code>Record</code> object, set a table to add a new row to; use <code>Record.set_field_value()</code> to set values to columns in the table, you must know columns and data type to set. At the end call <code>Record.save()</code> to add the new row.
+  </p>
+  <p>
+  <code>Record.set_field_value()</code> doesn't know if the columns and type is correct, just store the value to used in an INSERT statement; if key is set by database engine it will be added automatically, if not you must set it in order to execute <code>save()</code> with no errors.
+  </p>
+  </section>
+  <section id="record-subclass">
+  <title>Subclassing Record class</title>
+  <p>
+  <code>Record</code> class could be used as base for others. Is useful to wrap <code>Record.set_field_value()</code> into your class property to hide database access.
+  </p>
+  <note style="tip">
+  <p>Use <code>try{}</code><code> catch{}</code> to avoid warnings for unhandled error</p>
+  </note>
+  <listing>
+  <desc>
+  This code declares a new class MyRecord derived from Record.
+  </desc>
+  <code mime="text/x-c++src">
+  class MyRecord : Record
+  {
+    public MyRecord () { /* Your init code */ }
+    
+    public string name
+    {
+      get 
+      { 
+        try {
+          return this.get_value ("name");
+        }
+        catch (Error e) {
+          GLib.warning ("ERROR on getting value from name property: " + e.message)
+        } 
+      }
+      
+      set 
+      { 
+        try {
+          return this.set_field_value ("name", value);
+        }
+        catch (Error e) {
+          GLib.warning ("ERROR on setting value to name property: " + e.message)
+        } 
+      }
+    }
+  }
+  </code>
+  </listing>
+  <p>
+  The above code declares a <code>MyRecord.name</code> property witch uses <code>Record.get_value()</code> and <code>Record.set_field_value()</code> from its base class, to get and set its value.
+  </p>
+  </section>
+</page>
diff --git a/doc/mallard/gda-data/enable-vala-extensions.page b/doc/mallard/gda-data/enable-vala-extensions.page
new file mode 100644
index 0000000..fa4411d
--- /dev/null
+++ b/doc/mallard/gda-data/enable-vala-extensions.page
@@ -0,0 +1,27 @@
+<page xmlns="http://projectmallard.org/1.0/";
+	 type="topic" id="enable-vala-extensions">
+
+  <info>
+    <revision pkgversion="5.2" version="0.1" date="2012-01-18" status="incomplete" />
+    <credit type="author">
+      <name>Daniel Espinosa</name>
+      <email>despinosa src gnome org</email>
+    </credit>
+    <license>
+      <p>Creative Commons Share Alike 3.0</p>
+    </license>
+    <link type="topic" xref="index" />
+  </info>
+
+  <title>
+    Enable Vala Extensions
+  </title>
+  
+  <p>
+  When building GDA from sources you need to use --enable-gda-gi, --enable-vala and --enable-vala-extensions switches in order to get Vala Extensions compiled and be able to install.
+  </p>
+  <p>
+  Vala Extensions requires GObject Introspection and Vala compiler, versions >=1.3 and >=15.1 respectively, installed including its development files.
+  
+  </p>
+</page>
diff --git a/doc/mallard/gda-data/index.page b/doc/mallard/gda-data/index.page
new file mode 100644
index 0000000..08eb521
--- /dev/null
+++ b/doc/mallard/gda-data/index.page
@@ -0,0 +1,27 @@
+<page xmlns="http://projectmallard.org/1.0/";
+	type="guide" id="index">
+
+  <info>
+    <revision pkgversion="5.2" version="0.1" date="2012-03-26" status="incomplete"/>
+    <credit type="author">
+      <name>Daniel Espinosa</name>
+      <email>despinosa src gnome org</email>
+    </credit>
+    <license>
+      <p>Creative Commons Share Alike 3.0</p>
+    </license>
+  </info>
+
+  <title>
+    GDA Vala Extensions Documentation
+  </title>
+  <p>
+  This guide will shows you features and how to use Vala Extensions.
+  </p>
+  <p>
+  Is a set of Vala interfaces and classes to allow access to a database components like: records, tables, schemas, and others. Interfaces defines the required properties and methods, allowing any one to implement them using any database engine. Classes are implementations of these interfaces using GDA's Vala bindings; allowing to instance them directly or create derived classes.
+  </p>
+  <p>
+  Interfaces and classes uses Gee's classes to store data from database or to be saved to. Some properties provides Gee.Collection implementations to allow iterate through its data using standard Vala's foreach statement.
+  </p>
+</page>