
Using your models outside of TurboGears
=======================================


.. _ipython_session: 

Sample Python/Ipython Session
-----------------------------

(Status:  incomplete)

.. archive:: _download/
   :file: ../_static/wiki20/_download/tg_shell_setup.py

The script :arch:`tg_shell_setup.py` should be saved in your :file:`root directory`.
And from this directory run the shell command:


.. code-block:: sh

   $ ipython shell development.ini

>>> %run tg_shell_setup
>>> whos
>>> a = DBSession.query(Page).first()
>>> a.__dict__
>>> help(a)
>>> b = Page('second pagetitle', 'SecondPage of WikiWords wiki')
>>> DBSession.add(b)
>>> pages = DBSession.query(Page).all
>>> [(page.data, page.pagename, page.id) for page in pages]
>>> ...
>>> transaction.commit()
>>> quit()

You should see the output

.. literalinclude::  ipython_output.txt


.. _external_script:

Python scripts 
--------------

.. archive:: _download/
   :file: ../_static/wiki20/_download/wiki20_external.py

(Status:  incomplete)

Download :arch:`wiki20_external.py` and save it in your :file:`root directory`.
Run as usual from the command line.

.. code-block:: sh

   $ python wiki20_external.py

You can test your model and templates this way, and insert code from your
controllers as well.
The file outputs html to the screen - capture it in a file and view through your 
browser.

Further Exploration
============================================

Now that you have a working Wiki, there are a number of further places to explore:

#. You can add `JSON support via MochiKit <JSONMochiKit.html>`_.

#. You can learn more about the `Genshi templating engine <http://genshi.edgewall.org/wiki/Documentation/templates.html>`_.

#. You can learn more about the `SQLAlchemy ORM <http://www.sqlalchemy.org/>`_.

If you had any problems with this tutorial, or have ideas on how to make it
better, please let us know on the mailing list! Suggestions are almost always
incorporated.

Common problems:
=================

*  ``paster`` errors:

   -  have you installed TG2 in a virtual environment?
      If so, have you :ref:`activated the virtualenv<activate_virtualenv>`?
      Check your commandline prompt.
   -  ``paster`` commands must be issued from the root directory.
*  python errors:

   - Insert ``print`` or ``pprint`` commands in your code and read the 
     output on the ``paster serve`` terminal.
   - Try the code segment outside of turbogears in a debugger (see 
     :ref:`external_script`), or run your code in either in an ``ipython``
     or ``python shell`` (see :ref:`ipython_session`).
*  Genshi/XML errors:  your Genshi templates (views) must be valid XML 
   documents ,or TG2 will raise an exception.  Check your templates with 
   an XML validator:

   -  e.g. ``xmllint`` on linux or through Cygwin on Windows for example.

      .. code-block:: sh

        $ xmllint -noout wiki20/templates/\*.html

      will check all your templates at once.  With the ``-noout`` option, 
      output will be produced only if files are not valid XML.
   -  Use your browser to detect errors.

*  Database errors:  Turn on the ``sqlalchemy.echo`` option in your 
   development.ini file::

      [app:main]
      ...
      sqlalchemy.echo = true
  
   and check the SQL code emitted by SQLAlchemy in your ``paster serve``
   window.
   Experiment with this code in an ``sqlite`` interactive session,
   and with SQLAlchemy in the python/ipython shell.
    


