r6419 - trunk/gnue-appserver/doc/devguide

[reinhard]

Author: reinhard
Date: 2004-09-28 17:21:07 -0500 (Tue, 28 Sep 2004)
New Revision: 6419

Modified:
   trunk/gnue-appserver/doc/devguide/02-concepts.texi
   trunk/gnue-appserver/doc/devguide/03-basicdb.texi
   trunk/gnue-appserver/doc/devguide/devguide.texi
Log:
More work on developers guide.


Modified: trunk/gnue-appserver/doc/devguide/02-concepts.texi
===================================================================
--- trunk/gnue-appserver/doc/devguide/02-concepts.texi  2004-09-28 18:29:54 UTC 
(rev 6418)
+++ trunk/gnue-appserver/doc/devguide/02-concepts.texi  2004-09-28 22:21:07 UTC 
(rev 6419)
@@ -22,7 +22,7 @@
 database backend, it lets you define the underlying logic by writing program
 code in Python, a very powerful yet easy to learn language.
 
-In @GNUe, a database table and the related program code forms a logical unit
+In @GNUe, a database table and the related program code form a logical unit
 called a @dfn{class}.  A typical example for a class would be @samp{customer},
 being composed of a database table with columns like @samp{name},
 @samp{street}, and @samp{city}, and several pieces of program code defining
@@ -31,20 +31,20 @@
 record at all, or under which conditions the customer may be deleted from the
 database.
 
-To distinguish between the database layer and the @GNUe layer, we speak of
+To distinguish between the database layer and the @GNUe@ layer, we speak of
 @dfn{tables}, and @dfn{columns} for the database, and of @dfn{classes},
 @dfn{properties}, and @dfn{procedures} for the stuff we do in @GNUe.
 
 If you have ever dealt with object oriented programming, the word @emph{class}
-probably rings a bell for you.  But please be aware: although classes in @GNUe
-share some aspects of object oriented programming (like the association of code
-with data or some kind of polymorphism), there are still some important
-differences.  Most notably, @GNUe classes don't support inheritance.
+probably rings a bell for you.  But please be aware: although classes in
address@hidden@ share some aspects of object oriented programming (like the 
association
+of code with data or some kind of polymorphism), there are still some important
+differences.  Most notably, @GNUe@ classes don't support inheritance.
 
 
 @section Modules
 
-One of the main design goals of @GNUe was to be @emph{modular}.  Several
+One of the main design goals of @GNUe@ was to be @emph{modular}.  Several
 authors should be able to develop applications independently of each other, and
 these applications should be able to work together smoothly.  To reach this
 goal, it was necessary to introduce a concept of @dfn{namespaces} so that class
@@ -64,7 +64,7 @@
 
 @section Class Extension
 
-As mentioned above, @GNUe classes doesn't support the concept of inheritance.
+As mentioned above, @GNUe@ classes doesn't support the concept of inheritance.
 However, often a new module might want to change the behaviour of an existing
 class.  Given our above example, the "invoicing" module would not want to
 simple use the "item" class of the "stock" module, but it would want to add a

Modified: trunk/gnue-appserver/doc/devguide/03-basicdb.texi
===================================================================
--- trunk/gnue-appserver/doc/devguide/03-basicdb.texi   2004-09-28 18:29:54 UTC 
(rev 6418)
+++ trunk/gnue-appserver/doc/devguide/03-basicdb.texi   2004-09-28 22:21:07 UTC 
(rev 6419)
@@ -9,6 +9,8 @@
 your connections.conf file is set up correctly to allow connections to the
 running application server with the [appserver] connection.
 
address@hidden 
----------------------------------------------------------------------------
+
 @section General GCD Layout
 
 To define the classes for @GNUe, we use @dfn{GCD files}.  These files are a
@@ -17,8 +19,8 @@
 So for a start, let's look at a very simple GCD file:
 
 @example
-<module name="sample">
-  <class name="address">
+<module name="address">
+  <class name="person">
     <property name="name"   type="string(35)" />
     <property name="street" type="string(35)" />
     <property name="zip"    type="string(8)" />
@@ -27,4 +29,172 @@
 </module>
 @end example
 
address@hidden 
----------------------------------------------------------------------------
 
address@hidden Using GCD Files
+
+After having written the above GCD file, save it as @samp{address.gcd}.  Now we
+have to make @GNUe@ read and process our class definition.  We do this by
+typing
address@hidden
+gnue-readgcd address.gcd
address@hidden example
address@hidden
+at the command prompt.  This will teach @GNUe@ about our new class and make the
+database backend create the tables necessary to hold the data of this class.
+
+Please note that some databases don't allow adding new tables while there is an
+active connection to the database server, so you might have to kill the
+application server before entering the above command and restart it afterwards
+(this might be fixed in future).
+
+Now, as @GNUe@ has learned about our class, we are ready to display a form and
+enter data: type
address@hidden
+gnue-forms appserver://appserver/form/address_person
address@hidden example
address@hidden
+and enjoy your first application!
+
+Please note the syntax of the last part in the command line, consisting of the
+module name, an underscore, and the class name.  We call this the @dfn{fully
+qualified class name}.
+
+You will probably notice that the form doesn't look very good yet. Of course we
+will improve that later, but first let us analyze the content of our little
+example file so far.
+
address@hidden 
----------------------------------------------------------------------------
+
address@hidden Modules
+
+The outermost level in the XML hierarchy, the @dfn{root element}, is the
address@hidden  Everything we define in a GCD file is defined within a module,
+and you can have exactly one module per GCD file.
+
+The following attributes are valid for the @code{module} tag:
+
address@hidden @code
address@hidden name
+unique name of the module, namespace identifier for everything defined within
+the module (max.@: 35 characters, but usually not more than 10 characters,
+required)
+
address@hidden comment
+explanatory text, not used by the system in any way (max.@: 70 characters,
+optional)
address@hidden table
+
address@hidden 
----------------------------------------------------------------------------
+
address@hidden Classes
+
+Naturally, we start the module by defining a @code{class}.  The class tag can
+have the following attributes:
+
address@hidden @code
address@hidden name
+identifier for this class, has to be unique within the module (the length of
+this name plus the length of the module name should not exceed 30 characters,
+required)
+
address@hidden comment
+explanatory text, not used by the system in any way (max.@: 70 characters,
+optional)
+
address@hidden module
+may only be given if a class of a foreign module is extended; don't let this
+confuse you, this will be explained later, we've just put it here for the sake
+of completeness
address@hidden table
+
address@hidden 
----------------------------------------------------------------------------
+
address@hidden Properties
+
+The most important building blocks of a class definition are @code{property}
+tags, defining the data fields of the class. These attributes can be given for
+a @code{property} tag:
+
address@hidden @code
address@hidden name
+identifier for the property, has to be unique within the class (except for the
+case of class extension) (the length of this name plus the length of the module
+name should not exceed 30 characters, required)
+
address@hidden comment
+explanatory text, not used by the system in any way (max.@: 70 characters,
+optional)
+
address@hidden type
+data type of this property, see below (required)
+
address@hidden length
+maximum length of data stored in this property, if appropriate for the data
+type (optional)
+
address@hidden scale
+scale of data stored in this property, if appropriate for the data type
+(optional)
+
address@hidden nullable
address@hidden means the value of @code{None} is valid for this property, while
address@hidden means it is not (optional, defaults to @samp{true})
address@hidden table
+
address@hidden 
----------------------------------------------------------------------------
+
address@hidden Data Types
+
address@hidden@ supports the following basic data types:
+
address@hidden @code
address@hidden string
+Strings can hold arbitary text.  A length may be given and means a maximum
+length of the text; if no length is given, maximum length is limited only by
+the database backend in use.  As long as the backend supports Unicode, there is
+no limitation on the characters that may appear in the string.
+
address@hidden number
+Numbers can be defined with length only (meaning integers with the given
+maximum number of digits) or with length and scale (meaning a maximum number of
+digits as given in length, where exactly the number of digits given in scale
+are after the decimal point).
+
address@hidden boolean
+Booleans can only hold @code{TRUE} or @code{FALSE}.  Neither length nor scale
+may be given for booleans.
+
address@hidden date
+The valid range of dates depends on the capability of the database backend.
+Neither length nor scale may be given for date properties.
+
address@hidden time
+This stores an absolute time value and is heavily dependent on the database
+backend.  Future versions of GNUe might have features to unify the handling of
+time values for the different databases, but until then, time properties are
+not recommended.  Neither length nor scale may be given for time properties.
+
address@hidden datetime
+Datetime properties store a date and a time, often also called a
address@hidden  The valid range as well as the resolution depends on the
+database backend, and it is generally not recommended to use fractions of
+seconds as not all databases support this.  Neither length nor scale may be
+given for datetime properties.
address@hidden table
+
+Length and scale may also be given in the @code{type} attribute, after the name
+of the type, enclosed in parathenses, with a comma between length and scale.
+So
+
address@hidden
+<property name="foo" type="string(35)" />
+<property name="bar" type="number(12,2)" />
address@hidden example
address@hidden
+is equivalent to
+
address@hidden
+<property name="foo" type="string" length="35" />
+<property name="bar" type="number" length="12" scale="2" />
address@hidden example

Modified: trunk/gnue-appserver/doc/devguide/devguide.texi
===================================================================
--- trunk/gnue-appserver/doc/devguide/devguide.texi     2004-09-28 18:29:54 UTC 
(rev 6418)
+++ trunk/gnue-appserver/doc/devguide/devguide.texi     2004-09-28 22:21:07 UTC 
(rev 6419)
@@ -7,12 +7,6 @@
 @macro GNUe
 GNU Enterprise
 @end macro
address@hidden GNUe,
address@hidden,
address@hidden macro
address@hidden GNUe.
address@hidden
address@hidden macro
 
 @c ----------------------------------------------------------------------------
 
@@ -42,7 +36,7 @@
 @author Reinhard M@"uller
 @page
 @vskip 0pt plus 1filll
-Copyright @copyright{} 2002 Free Software Foundation
+Copyright @copyright{} 2004 Free Software Foundation
 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.1