[Modeling-cvs] ProjectModeling/Modeling/doc/UserGuide CustomObject.tex,1.5,1.6

[<sbi...@us...>]

Update of /cvsroot/modeling/ProjectModeling/Modeling/doc/UserGuide
In directory sc8-pr-cvs1:/tmp/cvs-serv22947/doc/UserGuide

Modified Files:
	CustomObject.tex 
Log Message:
Added documentation: handling custom types for attributes

Index: CustomObject.tex
===================================================================
RCS file: /cvsroot/modeling/ProjectModeling/Modeling/doc/UserGuide/CustomObject.tex,v
retrieving revision 1.5
retrieving revision 1.6
diff -C2 -d -r1.5 -r1.6
*** CustomObject.tex	4 Jul 2003 17:06:52 -0000	1.5
--- CustomObject.tex	21 Jul 2003 14:28:17 -0000	1.6
***************
*** 115,119 ****
      and works on the same principles.
  
! \section{Accessing the objects' properties\label{customobject-object-properties}}
  
      (quick notes, needs to be further documented)
--- 115,119 ----
      and works on the same principles.
  
! \section{Accessing the objects' properties\label{customobject-key-value-coding}}
  
      (quick notes, needs to be further documented)
***************
*** 227,231 ****
    >>> #
    ... # Now we will manipulate 'objs' without explicitly referring
!   ... # to its method
    ... 
    >>> for o in objs:
--- 227,231 ----
    >>> #
    ... # Now we will manipulate 'objs' without explicitly referring
!   ... # to its methods
    ... 
    >>> for o in objs:
***************
*** 273,275 ****
    Object  <Book.Book instance at 0x84a38b4>
         ["T'assieds pas sur le compte-gouttes", 4, None]
! \end{verbatim}
\ No newline at end of file
--- 273,393 ----
    Object  <Book.Book instance at 0x84a38b4>
         ["T'assieds pas sur le compte-gouttes", 4, None]
! \end{verbatim}
! 
! \chapter{Handling custom types for attributes\label{attribute-custom-type}}
! 
! The framework handles automatically a subset of built-in python types:
! \code{int}, \code{string}, \code{float} and date types
! (e.g. \code{mx.DateTime}
! %, \code{DCOracle2.OracleDate if you use Oracle
! ). We'll see here how you can make the framework automatically assign to
! attributes' values real objects.
! 
! \section{Example: using FixedPoint for a price attribute\label{attribute-custom-type-example}}
! 
!   Sometimes you need more than this. Let's take the test package
! \module{AuthorBooks}, and suppose we want to use
! \module{FixedPoint}\footnote{\code{FixedPoint} package can be found on
! \ulink{sourceforge}{http://fixedpoint.sourceforge.net/html/lib/module-FixedPoint.html}}.
! 
! \begin{itemize}
! 
! \item change the model so that price is a \code{string}/\code{VARCHAR} (was: a
!       \code{float}/\code{NUMERIC(10,2)}): we will store the \class{FixedPoint}
!       object as a string, not as a float, because of the inherent imprecision
!       which goes any (binary) representation of float\footnote{try to type
!       '\code{0.7}' in a python interpreter:\\
! \code{>{}>{}> 0.7}\\
! \code{0.69999999999999996}}
! 
! \item add \method{_setPrice()} and \method{_getPrice()} to
!   \class{AuthorBooks.Book}:
! 
! \begin{verbatim}
! 
!    PRECISION=2
!    def _setPrice(self, value):
!      if value is None: 
!        self._price=None
!      else:
!        self._price  = FixedPoint(value, PRECISION)
!      
!    def _getPrice(self):
!      if self._price:
!        return None
!      else:
!        return str(self._price)
!      
! \end{verbatim}
! 
! \end{itemize}
! 
! Now let's test this: (remember to change the DB schema so that table BOOK's
! attribute \code{price} is a \code{VARCHAR})
! 
! \begin{verbatim}
! >>> from fixedpoint import FixedPoint
! >>> from AuthorBooks.Book import Book
! >>> from Modeling.EditingContext import EditingContext
! >>> ec=EditingContext()
! >>> book=Book()
! >>> book.setTitle('Test FixedPoint')
! >>> book.setPrice(FixedPoint("3.341"))
! >>> book.getTitle(), book.getPrice()
! ('Test FixedPoint', FixedPoint('3.34', 2)) # precision=2
! >>> ec.insert(book)
! >>> ec.saveChanges()
! >>> book.getTitle(), book.getPrice()
! ('Test FixedPoint', FixedPoint('3.34', 2))
! \end{verbatim}
! 
!   Here you can check in you db that it was stored as a \code{varchar}, as
!   expected.  Start a new python and test the fetch:
! 
! \begin{verbatim}
! >>> from fixedpoint import FixedPoint
! >>> from Modeling.EditingContext import EditingContext
! >>> ec=EditingContext()
! >>> books=ec.fetch('Book')
! >>> books[0].getTitle(), books[0].getPrice()
! ('Test FixedPoint', FixedPoint('3.34', 2))
! \end{verbatim}
! 
!   As you can see, \class{FixedPoint} is now correctly and automatically
!   handled by the framework.
! 
! 
! 
! This technique can be used for any custom type you want to use. The next
! section gives some details on how this works.
! 
! \section{Behind the scenes\label{attribute-custom-type-behind-the-scenes}}
! 
! We have seen how to map any attribute's value to an instance of given
! class. Here again, this is the \module{KeyValueCoding} in action, as described
! in section~\ref{customobject-key-value-coding}.
! 
! The framework {\em always} accesses the attributes' values with the so-called
! "private" methods (\method{storedValueForKey()},
! \method{takeStoredValueForKey()}). We already know that they will try to use
! private setters/getters --such as \method{_setPrice()} and
! \method{_getPrice()}-- before the public ones --being
! \method{getPrice()} and \method{setPrice()}).
! 
!   So, what happens here is:
! \begin{enumerate}
! 
! \item when the framework is about to save the data, it collects the
!       attributes' value using \method{storedValueForKey}. This one finds
!       \method{_getprice()}, which gently returns the corresponding string,
!     
!       Note: the same happens for validation before saving: type checking also
!         calls \method{_getPrice()} and gets a string, so everything's ok.
!     
! \item when the framework fetches the data, it uses
!         \method{takeStoredValueForKey()} to initialize attributes' values; for
!         the attribute \code{price}, this method finds and calls
!         \method{_setPrice()} which turns the string back to
!         \class{FixedPoint}.
! 
! \end{enumerate}