[Modeling-cvs] ProjectModeling/Modeling/doc/UserGuide DefiningaModel.tex,1.17,1.18

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

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

Modified Files:
	DefiningaModel.tex 
Log Message:
Updated doc. for PyModel: organization of the section, defining defaults, component: Model

Index: DefiningaModel.tex
===================================================================
RCS file: /cvsroot/modeling/ProjectModeling/Modeling/doc/UserGuide/DefiningaModel.tex,v
retrieving revision 1.17
retrieving revision 1.18
diff -C2 -d -r1.17 -r1.18
*** DefiningaModel.tex	24 Aug 2003 14:33:31 -0000	1.17
--- DefiningaModel.tex	24 Aug 2003 16:55:51 -0000	1.18
***************
*** 606,609 ****
--- 606,615 ----
  \section{PyModels\label{pymodel}}

+ Now that we know the different components of a model, it is time to examine
+ how they can be practically defined. This section examines a python definition
+ of a model, and the next section will show how this can be done equivalently
+ in a xml-file.
+ 
+ 
  A PyModel is a python module that defines a variable \var{model} 
  that is of type \class{PyModel.Model}. Objects of type \class{Model} collect
***************
*** 617,620 ****
--- 623,651 ----
  and others may of course be defined as necessary. 

+ 
+ \subsection{Organization of this chapter}
+ 
+ The next section, \ref{pymodel-sample}, will give a full example of a PyModel.
+ 
+ 
+ Section~\ref{pymodel-defauls} will then discuss defaults: what they are, and
+ how they will be changed. It should be read before referring to the
+ components' details, since it explains important things that won't be repeated
+ afterwards.
+ 
+ 
+ Then, for each component of a model (\class{Model}, \class{Entity}, etc.), a
+ comprehensive list of available properties will be given, including their
+ default values. These properties are those we saw in
+ section~\ref{model-details}. We suppose here that the content of this section
+ is known, so if you need details about the meaning and effects of some
+ component's property, please refer to the component's detailed description,
+ above.
+ 
+ 
+ Last, please note that the section describing Models
+ (~\ref{pymodel-entity-props}) exposes in details how these properties can be
+ set; this information will not be repeated in the sections coming afterwards.
+ 
  \subsection{A sample PyModel\label{pymodel-sample}}

***************
*** 624,627 ****
--- 655,661 ----
  \class{APrimaryKey} and \class{AString}.

+ \makeatletter
+ \def\verbatim@font{\footnotesize\ttfamily}
+ \makeatother
  \begin{verbatim}
  from Modeling.PyModel import *
***************
*** 641,646 ****

  _connDict = {'database': 'AUTHOR_BOOKS'}
! model = Model('AuthorBooks',adaptorName='Postgresql',
!                 connDict=_connDict)
  model.version='0.1'
  model.entities = [
--- 675,679 ----

  _connDict = {'database': 'AUTHOR_BOOKS'}
! model = Model('AuthorBooks',adaptorName='Postgresql', connDict=_connDict)
  model.version='0.1'
  model.entities = [
***************
*** 648,653 ****
    Entity('Book',
           properties=[ AString('title', isRequired=1, columnName='title'),
!                       AFloat('price'),
!                       ],
           ),
    Entity('Writer',
--- 681,686 ----
    Entity('Book',
           properties=[ AString('title', isRequired=1, columnName='title'),
!                       AFloat('price'), 
! 	],
           ),
    Entity('Writer',
***************
*** 661,665 ****
           ),
    ]
- 
  model.associations=[
    Association('Book', 'Writer',
--- 694,697 ----
***************
*** 671,678 ****
    ]
  \end{verbatim}

! \subsection{Model\label{pymodel-entity-props}}

! tbd.

  \subsection{Entity\label{pymodel-entity-props}}
--- 703,777 ----
    ]
  \end{verbatim}
+ \makeatletter
+ \def\verbatim@font{\normalsize\ttfamily}
+ \makeatother

! A PyModel is typically made of two parts: a first part sets the defaults, then
! the second one defines the model. Defaults helps you keep the model definition
! tidy, by removing the repetitive parts from the model definition itself; in
! this example, the defaults add a primary key to each entity, sets the
! \code{width} for strings, etc.

! \subsection{Defaults\label{pymodel-defaults}}
! 
! In the coming description of the components of a model, you'll see that every
! possible property is assigned a default value.
! 
! This default value will be used if you omit it in your definition. For
! example, a component \class{AString} representing a string attribute has a
! default value of \code{255} assigned to its \code{width}. This default value
! may, or may be not, what you need. To avoid the unnecessary overhead of
! overwriting the defaults in each component \class{AString}, you can set a
! different default for one, or more, of its properties:
! \begin{verbatim}
! AString.defaults['width']=30
! AString.defaults['externalType']='TEXT'
! \end{verbatim}
! 
! This is a general mechanism that you can use for every single property defined
! by a component, simply by changing the corresponding entry in the component
! class's dictionary \code{defaults}.
! 
! \subsection{Model\label{pymodel-model-props}}
! 
! A model defines the following properties:
! 
! \begin{longtableiii}{p{3cm}p{4cm}p{7cm}}{code}{Prop.}{Default}{Comment}
! \lineiii{name}{\emph{no default}}{The \code{name} is the only mandatory
! arguments when instanciating a \class{Model}. Once set, it should not be
! changed}
! \lineiii{packageName}{value of \code{name}}{Dynamically }
! \lineiii{adaptorName}{\code{''}}{}
! \lineiii{connDict}
! {\code{\{ 'host': '', 'database': '', 'user': '', 'password': '' \}}}{}
! \lineiii{entities}{\code{[]}}{Entities for the model are appended to this
! sequence.}
! \lineiii{associations}{\code{[]}}{Associations are appended to this
! sequence.}
! \lineiii{doc}{\code{''}}{this is the ``comment'' field}
! \lineiii{version}{\emph{no default}}{}
! \end{longtableiii}
! 
! \begin{notice}
! For details about these properties and their meaning, please refer to~\ref{model-props}.
! \end{notice}
! 
! When instanciated, a model should supply its name:
! 
! \begin{verbatim}
! model = Model('AuthorBooks')
! \end{verbatim}
! 
! Properties can be set at instanciation time:
! 
! \begin{verbatim}
! model = Model('AuthorBooks', adaptorName='Postgresql')
! \end{verbatim}
! 
! or by direct assignment:
! 
! \begin{verbatim}
! model.adaptorName='Postgresql'}.
! \end{verbatim}

  \subsection{Entity\label{pymodel-entity-props}}
***************
*** 680,690 ****
  tbd.

! \subsection{Attribute\label{pymodel-entity-props}}

      AInteger, AString, AFloat, ADateTime, APrimaryKey, AForeignKey

! \subsubsection{Primary keys\label{pymodel-entity-props-primary-keys}}

! \subsubsection{ForeignKeys\label{pymodel-entity-props-foreign-keys}}

  \subsection{Relationship\label{pymodel-relationship-props}}
--- 779,789 ----
  tbd.

! \subsection{Attribute\label{pymodel-attribute-props}}

      AInteger, AString, AFloat, ADateTime, APrimaryKey, AForeignKey

! \subsubsection{Primary keys\label{pymodel-attribute-props-primary-keys}}

! \subsubsection{ForeignKeys\label{pymodel-attribute-props-foreign-keys}}

  \subsection{Relationship\label{pymodel-relationship-props}}
***************
*** 856,859 ****
--- 955,961 ----

  \subsection{Full format of an xml-model\label{full-xml-format}}
+ \makeatletter
+ \def\verbatim@font{\footnotesize\ttfamily}
+ \makeatother
  \begin{verbatim}
  <?xml version='1.0' encoding='iso-8859-1'?>
***************
*** 920,925 ****
  </model>
  \end{verbatim}
! 
! 
  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  \section{General guidelines and gotchas \label{guidelines-gotchas}}
--- 1022,1028 ----
  </model>
  \end{verbatim}
! \makeatletter
! \def\verbatim@font{\normalsize\ttfamily}
! \makeatother
  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  \section{General guidelines and gotchas \label{guidelines-gotchas}}