r6622 - trunk/gnue-appserver/doc/devguide

[reinhard]

Author: reinhard
Date: 2004-11-04 09:37:45 -0600 (Thu, 04 Nov 2004)
New Revision: 6622

Added:
   trunk/gnue-appserver/doc/devguide/05-references.texi
Modified:
   trunk/gnue-appserver/doc/devguide/04-ui.texi
   trunk/gnue-appserver/doc/devguide/devguide.texi
Log:
New chapter.


Modified: trunk/gnue-appserver/doc/devguide/04-ui.texi
===================================================================
--- trunk/gnue-appserver/doc/devguide/04-ui.texi        2004-11-04 13:10:45 UTC 
(rev 6621)
+++ trunk/gnue-appserver/doc/devguide/04-ui.texi        2004-11-04 15:37:45 UTC 
(rev 6622)
@@ -1,4 +1,4 @@
address@hidden $Date: 2004-10-18 15:30:28 +0200 (Mon, 18 Oct 2004) $
address@hidden $Date$
 
 @chapter Basic User Interface Features
 


Property changes on: trunk/gnue-appserver/doc/devguide/04-ui.texi
___________________________________________________________________
Name: svn:keywords
   + Date

Added: trunk/gnue-appserver/doc/devguide/05-references.texi
===================================================================
--- trunk/gnue-appserver/doc/devguide/05-references.texi        2004-11-04 
13:10:45 UTC (rev 6621)
+++ trunk/gnue-appserver/doc/devguide/05-references.texi        2004-11-04 
15:37:45 UTC (rev 6622)
@@ -0,0 +1,119 @@
address@hidden $Date$
+
address@hidden Referencing Other Classes
+
+So far, we have only defined a single class in our module.  However, a database
+design in practice usually consists of several classes, and these classes
+reference each other.  We will now see how we define several classes in a
+module and their relationship with each other.
+
address@hidden 
----------------------------------------------------------------------------
+
address@hidden Defining Several Classes In A Module
+
+Definition of more than one class within a module is very straightforward -
+just include a @code{<class>} tag for each class within a single
address@hidden<module>} tag in the GCD file:
+
address@hidden
+<module name="address">
+  <class name="country">
+    <property name="code"   type="string(2)" comment="ISO-Code" />
+    <property name="name"   type="string(35)" />
+  </class>
+  <class name="person">
+    <property name="name"   type="string(35)" />
+    <property name="street" type="string(35)" />
+    <property name="zip"    type="string(8)" />
+    <property name="city"   type="string(35)" />
+  </class>
+</module>
address@hidden example
+
+The same works for GLD files:
+
address@hidden
+<module name="address" language="C">
+  <class name="country">
+    <property name="code"   pos="100" label="ISO Code" />
+    <property name="name"   pos="200" label="Name" />
+  </class>
+  <class name="person">
+    <property name="name"   pos="100" label="Name" />
+    <property name="street" pos="200" label="Street" />
+    <property name="zip"    pos="300" label="Zip-Code" />
+    <property name="city"   pos="400" label="City" />
+  </class>
+</module>
address@hidden example
+
+Please note this will result in two separate forms you will be able to call:
+
address@hidden
+gnue-forms appserver://appserver/form/address_country
+gnue-forms appserver://appserver/form/address_person
address@hidden example
+
+Don't forget that you have to run @code{gnue-gcd} after you have changed a GCD
+file, and @code{gnue-gld} after you have changed a GLD file!
+
address@hidden 
----------------------------------------------------------------------------
+
address@hidden Reference Properties
+
+Of course we will now want to link our two classes together: The person class
+should not only store the street, the zip and the city, but also the country to
+make up a complete address.
+
+We achieve this in adding a new property to the person class.  But this new
+property will not contain a string with the country code or name, it will
+rather just @dfn{reference} an instance of the country class.
+
+A reference property is defined in the GCD file by giving the referenced class
+as type of the property:
+
address@hidden
+<property name="country"   type="address_country" />
address@hidden example
+
+And again we see that @dfn{fully qualified classname}, consisting of the module
+name, an underscore, and the class name.
+
+In the GLD file, a reference property is handled similar to a normal property:
+
address@hidden
+<property name="country" pos="500" label="Country" />
address@hidden example
+
+However, there's something missing: What should the form display for the
+country? Should the country code be displayed? The name of the country? Both of
+them? How will the user see what countries are valid?
+
+The most usual concept here is to display a dropdown in the form that lists all
+available countries, and to let the user select one of them. But still we have
+to define which property of the @samp{country} class should be listed in the
+dropdown. This is done in the GLD file for the @samp{country} class:
+
address@hidden
+<class name="country">
+  <property name="code"   pos="100"              label="ISO Code" />
+  <property name="name"   pos="200" search="100" label="Name" />
+</class>
address@hidden example
+
+The @samp{search="100"} defines that exactly this property will be listed in
+the dropdown for the user to select from. You can try to move that part to the
address@hidden property, and you will see that the dropdown will be filled with
+country codes instead of country names.
+
+Even more, you can have more than one property in a class with a @code{search}
+attribute: this will result in several dropdowns being displayed side by side,
+in the order of the number given for the @code{search} attribute. Try making
+the code property @samp{search="100"} and the name property @samp{search="200"}
+and look at the result. Then, try the other way around. You will see how
+flexible this system is.
+
+Please note that this is defined in the GLD for the @emph{referenced} class, in
+our case the @samp{country} class. That means that @emph{every other class}
+referencing a country will show the @emph{same} dropdowns in the user
+interface.


Property changes on: trunk/gnue-appserver/doc/devguide/05-references.texi
___________________________________________________________________
Name: svn:keywords
   + Date

Modified: trunk/gnue-appserver/doc/devguide/devguide.texi
===================================================================
--- trunk/gnue-appserver/doc/devguide/devguide.texi     2004-11-04 13:10:45 UTC 
(rev 6621)
+++ trunk/gnue-appserver/doc/devguide/devguide.texi     2004-11-04 15:37:45 UTC 
(rev 6622)
@@ -70,6 +70,7 @@
 * General Concepts::
 * Basic DB Features:: Basic Database Features
 * Basic UI Features:: Basic User Interface Features
+* References:: Referencing Other Classes
 @end menu
 
 @c    Node               Next               Previous           Up
@@ -79,7 +80,9 @@
 @include 02-concepts.texi
 @node Basic DB Features, Basic UI Features, General Concepts,  Top
 @include 03-basicdb.texi
address@hidden Basic UI Features, (null),            Basic DB Features, Top
address@hidden Basic UI Features, References,        Basic DB Features, Top
 @include 04-ui.texi
address@hidden References,        (null),            Basic UI Features, Top
address@hidden 05-references.texi
 
 @bye