r6835 - trunk/gnue-appserver/doc/devguide

[reinhard]

Author: reinhard
Date: 2004-12-29 05:56:10 -0600 (Wed, 29 Dec 2004)
New Revision: 6835

Added:
   trunk/gnue-appserver/doc/devguide/06-procedures.texi
Modified:
   trunk/gnue-appserver/doc/devguide/devguide.texi
Log:
Added new chapter about procedures. Thanks to Johannes for drafting most of the
text.


Added: trunk/gnue-appserver/doc/devguide/06-procedures.texi
===================================================================
--- trunk/gnue-appserver/doc/devguide/06-procedures.texi        2004-12-28 
22:10:55 UTC (rev 6834)
+++ trunk/gnue-appserver/doc/devguide/06-procedures.texi        2004-12-29 
11:56:10 UTC (rev 6835)
@@ -0,0 +1,214 @@
address@hidden $Date$
+
address@hidden Defining And Using Procedures
+
+As mentioned before, procedures are the second element classes in GNU
+Enterprise are built upon.  GNU Enterprise is designed to generally support
+different programming languages for procedures, and while Python is the only
+language currently supported, others might follow.
+
+Procedures can have zero, one, or more than one parameters, and they may have
+or have not a return value. All parameters and the return value must be of a
+fixed datatype.
+
+Procedures are defined in the GCD file.
+
address@hidden 
----------------------------------------------------------------------------
+
address@hidden Triggers
+
address@hidden are procedures that are called automatically by the GNU
+Enterprise system on occurance of predefined events.  Triggers have no
+parameters and no return value.
+
+
address@hidden OnInit
+
+If a class contains a procedure with the name @code{OnInit}, the code in this
+procedure is automatically executed whenever a new instance of this class is
+created.
+
address@hidden procedures are usually used to initialize properties with default
+values.  An instance that has seen no changes except that @code{OnInit} has run
+is still considered empty and is not affected by a commit.  In other words:
+Changes to an instance done in @code{OnInit} will be silently discarded when
+this instance is not saved afterwards. @address@hidden may not have side
+effects!}
+
+This example initializes the name for newly created person instances with
+"`Foo"'.
+
address@hidden
+<module name="address">
+  <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)" />
+
+    <procedure name="OnInit" >
+      self.name = 'Foo'
+    </procedure>
+  </class>
+</module>
address@hidden example
+
+
address@hidden OnChange
+
+If a class contains a procedure with the name @code{OnChange}, the code in this
+procedure is executed whenever a property is changed.
+
+The code in this procedure can access the variable @code{oldValue} to access
+the value before the change, @code{newValue} to access the value that the
+property should be changed to, and @code{propertyName} to see what property is
+being changed.
+
address@hidden is executed once for every single property that is changed. If
+several properties are changed in a single step, @code{OnChange} is executed
+for every property sequentially.
+
+It is possible to call the function @code{abort} in @code{OnChange}.  This
+function exits the current procedure and prevents the change to the property to
+happen. @code{abort} takes a single parameter, the error message to be
+presented to the user.
+
+The following example shows how to make sure that no zip codes greater than
+10000 can be entered:
+
address@hidden
+<module name="address">
+  <class name="person">
+    ...
+
+    <procedure name="OnChange" >
+      <![CDATA[
+      if propertyName == 'address_zip':
+        if newValue and int (newValue) < 10000:
+          abort ('ZIP codes must be greater than 10000')
+      ]]>
+    </procedure>
+  </class>
+</module>
address@hidden example
+
+
address@hidden OnValidate
+
+If a class defines a procedure with the name @code{OnValidate}, the code in
+this procedure is executed right before a commit.
+
+Every commit triggers the execution of @code{OnValidate} for all affected
+instances in more or less random order.  Changes done in @code{OnValidate} will
+become persistent with the current commit.  However, if the code in
address@hidden affects other instances, these changes are not guaranteed to
+run through the @code{OnValidate} of the other class (but this might change in
+the future).
+
address@hidden can prevent the commit to happen if it raises an exception
+with @code{abort} or by other means.
+
+Typical uses of @code{OnValidate} are calculation of redundant properties from
+other properties, automatic filling of properties that has side effects and
+therefore may not happen in @code{OnInit} (like getting the next sequential
+number), and of course validation.
+
+
address@hidden OnDelete
+
+If a class contains a procedure named @code{OnDelete}, the code in this
+procedure is executed whenever an instance is about to be deleted.
+
address@hidden can prevent the deletion to happen if it raises an exception
+with @code{abort} or by other means.
+
+Typical uses of @code{OnDelete} are to prevent deletion of instance under
+specific conditions, or to automatically delete detail records along with a
+master.
+
+
address@hidden 
----------------------------------------------------------------------------
+
address@hidden Calculated Properties
+
+Apart from the properties that are stored in the database, GNU Enterprise
+supports a kind of virtual properties that are determined at runtime as the
+result of a procedure.  We call them @dfn{calculated properties}.
+
+The following example shows a very simple calculated property that is built as
+a concatenation of country code, zip, and city.
+
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="country" type="address_country" />
+    <property name="zip"     type="string(8)" />
+    <property name="city"    type="string(35)" />
+
+    <property name="czc"     type="string(47)" />
+      return self.country.code + ' ' + self.zip + ' ' + self.city
+    </property>
+  </class>
+</module>
address@hidden example
+
+The possibilities of calculated properties are virutally unlimited.  You can
+access all other properties of the instance (even other calculated properties),
+properties of related or unrelated other instances, and you can even call
+external programs.  It is strongly advised, however, that the code in
+calcluated properties does not have any side effects.
+
+Whenever a calculated property with the name @samp{foo} is defined, GNU
+Enterprise defines a procedure with the name @samp{getfoo}, and every access to
+the property @samp{foo} is automatically and transparenty translated into a
+call of the @samp{getfoo} procedure.  However, the only reason why you need to
+know this at all is that you should not start the name of any of your
+procedures with @code{get}.
+
+The labels for calculated properties are defined in a GLD file just like for
+other properties.
+
address@hidden 
----------------------------------------------------------------------------
+
address@hidden Other Procedures
+
+Apart from triggers and calcuated properties, arbitary procedures can be
+defined with names not starting with @code{On} or @code{get} (independent from
+case).  These procedures may or may not have parameters, and they may or may
+not have return values, and they may contain virtually anything.
+
address@hidden Defining Parameters
+
+TBD
+
address@hidden Calling Procedures From Other Procedures
+
+Within procedure code (also within the code of triggers and calculated fields),
+all defined procedures are available as methods of the respective objects.
+
+In Python, parameters must be given as keyword arguments.
+
+The following examples show a few ways of calling procedures:
+
address@hidden
+self.foo ()
+self.bar (baz = 17)
+self.customer.doit (really = True)
+self.invoice.customer.doSomething (text = "foo", other = "bar")
address@hidden example
+
address@hidden Calling Procedures From Forms
+
+TBD
+
address@hidden 
----------------------------------------------------------------------------
+
address@hidden Global Functions And Variables Available In Procedures
+
+TBD: self, session, abort


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

Modified: trunk/gnue-appserver/doc/devguide/devguide.texi
===================================================================
--- trunk/gnue-appserver/doc/devguide/devguide.texi     2004-12-28 22:10:55 UTC 
(rev 6834)
+++ trunk/gnue-appserver/doc/devguide/devguide.texi     2004-12-29 11:56:10 UTC 
(rev 6835)
@@ -71,6 +71,7 @@
 * Basic DB Features:: Basic Database Features
 * Basic UI Features:: Basic User Interface Features
 * References:: Referencing Other Classes
+* Procedures:: Defining And Using Procedures
 @end menu
 
 @c    Node               Next               Previous           Up
@@ -82,7 +83,9 @@
 @include 03-basicdb.texi
 @node Basic UI Features, References,        Basic DB Features, Top
 @include 04-ui.texi
address@hidden References,        ,                  Basic UI Features, Top
address@hidden References,        Procedures,        Basic UI Features, Top
 @include 05-references.texi
address@hidden Procedures,        ,                  References,        Top
address@hidden 06-procedures.texi
 
 @bye