Turbogears experiment with Toscawidgets
#######################################

Turbogears
==========

Turbogears 1
------------

Based on the `wiki20 demo`_ from https://www.turbogears.org

.. code-block:: bash

    sudo pip install tg.devtools

.. _wiki20 demo: http://www.turbogears.org/1.0/docs/Wiki20/Page1.html

Turbogears 2
------------


.. code-block:: bash

    sudo pip3 install tg.devtools

Create a project
----------------

.. code-block:: bash

   gearbox quickstart wiki20


+------------------------------+---------------------------------------------------------------------------------------------+
| wiki20/...                   | Purpose or function                                                                         |
+==============================+=============================================================================================+
| development.ini              | Configures the dev environment and dev web server                                           |
+------------------------------+---------------------------------------------------------------------------------------------+
| MANIFEST.in                  | Distribution manifest for sdist                                                             |
+------------------------------+---------------------------------------------------------------------------------------------+
| migration/env.py             | SQL Alchemy environment                                                                     |
+------------------------------+---------------------------------------------------------------------------------------------+
| migration/script.py.mako     | SQL Alchemy template                                                                        |
+------------------------------+---------------------------------------------------------------------------------------------+
| __pycache__                  | Compiled Cpython instructions for setup                                                     |
+------------------------------+---------------------------------------------------------------------------------------------+
| README.txt                   | Operating instructions for gearbox                                                          |
+------------------------------+---------------------------------------------------------------------------------------------+
| setup.cfg                    | TG and TW configuration options                                                             |
+------------------------------+---------------------------------------------------------------------------------------------+
| setup.py                     | Package configuration                                                                       |
+------------------------------+---------------------------------------------------------------------------------------------+
| test.ini                     | Test environment configuration options                                                      |
+------------------------------+---------------------------------------------------------------------------------------------+
| wiki20.egg-info              | Python single-version-externally-managed path                                               |
+------------------------------+---------------------------------------------------------------------------------------------+
| wiki20/__init__.py           | Package wrapper for wiki20                                                                  |
+------------------------------+---------------------------------------------------------------------------------------------+
| wiki20/config                | Where project setup and configuration relies                                                |
+------------------------------+---------------------------------------------------------------------------------------------+
| wiki20/controllers           | All the project controllers, the logic of our web application                               |
+------------------------------+---------------------------------------------------------------------------------------------+
| wiki20/i18n                  | Translation files for the languages supported                                               |
+------------------------------+---------------------------------------------------------------------------------------------+
| wiki20/lib                   | Utility python functions and classes                                                        |
+------------------------------+---------------------------------------------------------------------------------------------+
| wiki20/model                 | Database models                                                                             |
+------------------------------+---------------------------------------------------------------------------------------------+
| wiki20/public                | Static files like CSS, javascript and images                                                |
+------------------------------+---------------------------------------------------------------------------------------------+
| wiki20/templates             | Templates exposed by our controllers.                                                       |
+------------------------------+---------------------------------------------------------------------------------------------+
| wiki20/tests                 | Tests                                                                                       |
+------------------------------+---------------------------------------------------------------------------------------------+
| wiki20/websetup              | Functions to execute at application setup. Like creating tables, a standard user and so on. |
+------------------------------+---------------------------------------------------------------------------------------------+

Track dependencies
------------------

In wiki20/setup.py...

.. code-block:: python

    install_requires = [
        "TurboGears2 >= 2.3.9",
        "Babel",
        "Beaker",
        "Kajiki",
        "zope.sqlalchemy >= 0.4",
        "sqlalchemy",
        "alembic",
        "repoze.who",
        "tw2.forms",
        "tgext.admin >= 0.6.1",
        "WebHelpers2",
        "docutils" # added to the default
    ]

Then install what we need with pip3.

.. code-block:: bash

    pip3 install -e .

Start dev server
----------------

The dev web server should start by default on http://127.0.0.1:8080.

See your configuration at http://127.0.0.1:8080/environ.

.. code-block:: bash

    # development.ini informs the defaults for this
    gearbox serve --reload --debug

Controller-Model-View (CMV) structure
-------------------------------------

Controllers and templates (views)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The *@expose()* decorator exposes objects to the web.

The code below from the *RootController(BaseController)* class will present the front page
 from the template in *wiki20/wiki20/templates/index.xhtml*.

.. code-block:: python

    @expose('wiki20.templates.index')
    def index(self):
        """Handle the front-page."""
        return dict(page='index')