[Pymerase-cvs-commit] Docs/linkDB-tutorial linkdb-tutorial.tex,1.3,1.4

[<ki...@us...>]

Update of /cvsroot/pymerase/Docs/linkDB-tutorial
In directory sc8-pr-cvs1:/tmp/cvs-serv12741

Modified Files:
	linkdb-tutorial.tex 
Log Message:
continuing the tutorial


Index: linkdb-tutorial.tex
===================================================================
RCS file: /cvsroot/pymerase/Docs/linkDB-tutorial/linkdb-tutorial.tex,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** linkdb-tutorial.tex	12 Mar 2003 06:53:17 -0000	1.3
--- linkdb-tutorial.tex	13 Mar 2003 02:30:14 -0000	1.4
***************
*** 31,35 ****
  \author{Brandon King \\
  Copyright \copyright  California Institute of Technology}
! \date{Version 0.1.3\\\today}
  \maketitle
  \thispagestyle{empty}
--- 31,35 ----
  \author{Brandon King \\
  Copyright \copyright  California Institute of Technology}
! \date{Version 0.1.4\\\today}
  \maketitle
  \thispagestyle{empty}
***************
*** 93,96 ****
--- 93,97 ----
      \item Python Language\footnote{Python Tutorial:
        http://www.python.org/doc/current/tut/tut.html}
+     \item PostgreSQL
    \end{itemize}
  
***************
*** 186,194 ****
  files, run the command below.
  
! \textcolor{blue}{unzip linkDB.zargo linkDB\_.xmi}
  
  If that command fails, try this command:
  
! \textcolor{blue}{unzip linkDB.zargo}
  
  You should find a .xmi file in your directory. This is the file which
--- 187,199 ----
  files, run the command below.
  
! \begin{verbatim}
! unzip linkDB.zargo linkDB_.xmi
! \end{verbatim}
  
  If that command fails, try this command:
  
! \begin{verbatim}
! unzip linkDB.zargo
! \end{verbatim}
  
  You should find a .xmi file in your directory. This is the file which
***************
*** 264,267 ****
--- 269,278 ----
  'pymerase.input.parseXMI' for the input module.
  
+ \subsection{\cb Todo for All Templates}
+ For each of the driver programs you will create .py file and paste in
+ the template from section \ref{template}. Changed the
+ schema path to the path were your .xmi file we extracted in section
+ \ref{xmi} and that you replace 'nameOfInputModule' with 'parseXMI'.
+ 
  
  \subsection{\cb Create SQL for Database}\label{sql}
***************
*** 303,310 ****
  \end{verbatim}
  
! \subsection{\cb Create Database API}
  The \textcolor{blue}{CreateDBAPI} output module is used to generate a
  Python Database API to the database you will generate from the SQL in
  section \ref{sql}.
  
  \end{document}
--- 314,574 ----
  \end{verbatim}
  
! \subsection{\cb Create Python Database API (DBAPI)}
  The \textcolor{blue}{CreateDBAPI} output module is used to generate a
  Python Database API to the database you will generate from the SQL in
  section \ref{sql}.
+ 
+ Create a new file in your tutorial directory named 'createapi.py'
+ and paste in the driver program template from section
+ \ref{template}. Change the output path from './outputPath' to
+ './LinkAPI' and change 'nameOfOutputModule' to 'CreateDBAPI'.
+ 
+ \subsection{\cb Create Python Tkinter Widgets}
+ The \textcolor{blue}{CreatePyTkWidgets} output module is used to
+ generate a library of Python Tkinter Widgets based on the schema
+ you used to generate the widgets. You would use this if you would
+ quickly like to create a GUI for your application.
+ 
+ Create a new file in your tutorial directory named
+ 'createpytkwidgets.py' and paste in the driver program template from
+ section \ref{template}. Change the output path from './outputPath' to
+ './widgets' and change 'nameOfOutputModule' to 'CreatePyTkWidgets'.
+ 
+ \subsection{\cb Create Python Tkinter Database Widgets}
+ The \textcolor{blue}{CreatePyTkDBWidgets} output module is used to
+ create a few more widgets to the library of Python Tkinter
+ Widgets. These widgets have been linked up to the DBAPI for your
+ database, and will allow you view, edit, and create new records in
+ your database.
+ 
+ Create a new file in your tutorial directory named
+ 'createpytkdbwidgets.py' and paste in the driver program template from
+ section \ref{template}. Change the output path from './outputPath' to
+ './widgets' and change 'nameOfOutputModule' to 'CreatePyTkDBWidgets'.
+ 
+ \subsection{\cb Other Output Modules}
+ You may wish to generate other output modules in addition to the four
+ used in this tutorial. For a complete list of Output modules, visit
+ the Pymerase Docs - Output Modules web page\footnote{http://pymerase.sf.net/docs/output/}.
+ 
+ 
+ 
+ %Section: Generate Files with Pymerase
+ \section{\cb Tutorial: Generating Files with Pymerase}
+ 
+ \subsection{\cb Description}
+ Now you should have at least the following files in your tutorial
+ directory.
+ 
+ \begin{itemize}
+   \item linkDB.zargo
+   \item linkDB\_.xmi
+   \item createsql.py
+   \item createapi.py
+   \item createpytkwidgets.py
+   \item createpytkdbwidgets.py
+ \end{itemize}
+ 
+ In this section we will generate all the files we will need to make
+ our command line program that will accomplish our goal from section
+ \ref{the_goal}.
+ 
+ \subsection{\cb CreateSQL}
+ Time to create the sql for the database. Executed the following
+ command.
+ 
+ \begin{verbatim}
+ jython ./createsql.py
+ \end{verbatim}
+ 
+ If everything goes well, you should find a file called linkDB.sql in
+ your tutorial directory. If something goes wrong, you probably don't
+ have jython and/or pymerase setup correctly. Read the Pymerase
+ Installation Documentation\footnote{http://pymerase.sf.net/docs/} or
+ e-mail the pymerase-devel mailing list mentioned in section
+ \ref{pymdevel}.
+ 
+ \subsection{\cb CreateDBAPI}\label{linkapi}
+ Now execute the following command to create the DBAPI.
+ 
+ \begin{verbatim}
+ jython ./createapi.py
+ \end{verbatim}
+ 
+ If everything went well, you should find a python package called
+ 'LinkAPI'. We will use this later to access the data from our
+ database.
+ 
+ Here is a quick example of how to use the DBAPI\footnote{Check the pymerase
+ docs or e-mail the mailing list mentioned in section \ref{pymdevel}
+ for more help.}.
+ 
+ \begin{verbatim}
+ #!/usr/bin/env python
+ 
+ from LinkAPI import DBSession
+ 
+ if __name__ == '__main__':
+   dbs = DBSession(dsn='localhost',
+                   database='linkdb',
+ 		  user='userName',
+ 		  password=None)
+ 
+   
+   #get all name link pairs
+   nameLinkPairList = dbs.getAllObjects(dbs.NameLinkPair)
+ 
+   #get all groups
+   groupList = dbs.getAllObjects(dbs.Group)
+ 
+   #get group with primary key of 1
+   groupId1 = dbs.getObject(dbs.Group, '1')
+ 
+   #get name link pairs with primary keys 1, 3, 4
+   nlpKeys134 = dbs.getObject(dbs.NameLinkPair,
+                              ['1', '3', '4'])
+ 
+   #get group by database field 'name'
+   nameGroup = dbs.getObjectWhere(dbs.Group, 'name = \'myGroup\')
+ 
+   #get NameLinkPairs associated with 'myGroup'
+   myGroup = nameGroup[0]
+ 
+   nlp4myGroupList = myGroup.getNameLinkPair()
+ 
+ \end{verbatim}
+ 
+ 
+ \subsection{\cb CreatePyTkWidgets}
+ Excute the following command to generate the Python Tkinter Widget
+ library for your schema.
+ 
+ \begin{verbatim}
+ jython ./createpytkwidgets.py
+ \end{verbatim}
+ 
+ You will be prompted for the name of the DBAPI package you want to use
+ with these widgets. In this case, you will enter 'LinkAPI'.
+ 
+ If everything went well, you should have a directory named 'widgets'
+ in your tutorial directory. In that directory you should find the
+ following widgets.
+ 
+ \begin{tabular}{ll}
+ ExtendedOptionMenu.py & Adds funtionality to OptionMenu widget.\\
+ \emph{allOther}Widget.py & Entry Widgets for user entry of data.\\
+ NavBar.py & Controls entry widget navigation.\\
+ SaveWidget.py & Tells a given Entry Widget to save itself.\\
+ ValidatingEntr.py & Adds validation to Tkinter Entry widgets.\\
+ dbSession.py & Session Object for passing information around.\\
+  & Also contains a generic DB connection widget.\\
+ modes.py & Static variables for choosing widget mode.
+ \end{tabular}
+ 
+ All \emph{allOther}Widget.py files can be executed to see if they were
+ contstructed properly. They don't do much in this state, but the have
+ functions for getting and setting the ValiditingEntrys. Each of
+ widgets can be subclassed and given save() and load() functions which
+ will then allow them to be hooked up to the SaveWidget and NavBar
+ widgets. In the next section we will generate Python Tkinter Database
+ Widgets which use these features.
+ 
+ For more information on the entry widgets, please visit the Pymerase
+ Docs web site or send e-mail to the mailing list mentioned in section
+ \ref{pymdevel}.
+ 
+ The widgets will need a copy of the LinkAPI package you generated in
+ section \ref{linkapi}. You can copy, move, or create a symbolic link
+ for this purpose. Excute the following command to copy the pakage from
+ your tutorial directory into the widget directory.
+ 
+ \begin{verbatim}
+ cp -r LinkAPI/ widgets/
+ \end{verbatim}
+ 
+ \subsection{\cb CreatePyTkDBWidgets}
+ Excute the following command to generate the Python Tkinter Database
+ Widget library for your schema.
+ 
+ \begin{verbatim}
+ jython ./createpytkwidgets.py
+ \end{verbatim}
+ 
+ You will be prompted for the name of the DBAPI package you want to use
+ with these widgets. In this case, you will enter 'LinkAPI'.
+ 
+ If all went well, you should find \emph{allOther}DbWidget.py files in
+ your widget directory. Each of these programs can be executed upon
+ creation. Each one if hooked up to the generic DB connection widget
+ and will prompt for infomation neccisary to connect to the
+ database. It can become annoying sometimes when you have to enter that
+ information every time you want to connect to the same database. So,
+ there is a 'db.cfg' file you can drop into the widget directory. Here
+ is an example.
+ 
+ \begin{verbatim}
+ [Connect]
+ dsn: localhost
+ database: linkdb
+ user: userName
+ password:
+ \end{verbatim}
+ 
+ If the connection to the database fails using the config file, it will
+ load the generic connection widget and load the config file values
+ into it.
+ 
+ We will use these DbWidgets to input data into our database later in
+ the tutorial.
+ 
+ 
+ %Section: Setting Up the Database
+ \section{\cb Tutorial: Setting Up the Database}
+ 
+ \subsection{\cb PostgreSQL Setup}
+ If you have not installed PostgreSQL 7.2 or higher, you should do so
+ now. If you have installed PostgreSQL and have configured it to your
+ liking, move on to the next section. If you get stuck, the mailing
+ list in section \ref{pymdevel} is there for you.
+ 
+ \subsection{\cb Create the linkdb Database}
+ The first thing we need to do is create the linkdb database. If you
+ are running linux, you can use the following command.
+ 
+ \begin{verbatim}
+ createdb -h localhost -U userName linkdb
+ \end{verbatim}
+ 
+ If you get the message 'CREATE DATABASE', the command succeded. Next
+ you need to feed the SQL statements into the database to generate the
+ proper tables. User the following command.
+ 
+ \begin{verbatim}
+ psql -h localhost -U userName linkdb < linkDB.sql
+ \end{verbatim}
+ 
+ If you get the following message, everything went well.
+ 
+ \begin{verbatim}
+ CREATE
+ NOTICE:  CREATE TABLE / PRIMARY KEY will create implicit
+    index 'group_pkey' for table 'group'
+ CREATE
+ CREATE
+ NOTICE:  CREATE TABLE / PRIMARY KEY will create implicit
+    index 'name_link_pair_pkey' for table 'name_link_pair'
+ CREATE
+ \end{verbatim}
+ 
+ \subsection{\cb Input Data Using DB Widgets}
+ Now that we have our database, lets put some data in it for us to
+ use. Goto the widgets directory in your tutorial directory. Execute
+ the following command.
+ 
+ \begin{verbatim}
+ python ./GroupDbWidget.py
+ \end{verbatim}
+ 
+ %continue here
  
  \end{document}