==========
Design
==========

Following is a quick overview of our wiki application, to help
us understand the changes that we will be doing next in our
default files generated by the paster scafffold.

Overall
-------

We choose to use ``reStructuredText`` markup in the wiki text.
Translation from reStructuredText to HTML is provided by the
widely used docutils Python module.  We will add this module
in the dependency list on the project ``setup.py`` file.

Models
------

We define a single table named `tables`, whose elements will
store the wiki pages.  There are two columns: `name` and 
`data`.

URLs like ``/PageName`` will try to find an element in 
the table whose `name` corresponds.

To add a page to the wiki, a new row is created and the text
is stored in `data`.

A page named *FrontPage* containing the text *This is the front
page*, will be created when the storage is initialized, and will
be used as the wiki home page.

Views
-----

There will be four views to handle the normal operations of
viewing, editing and adding wiki pages.  Two additional views
will handle the login and logout tasks related to security.

Security
--------

- USERS, a dictionary mapping users names to their
  corresponding passwords.
- GROUPS, a dictionary mapping user names to a 
  list of groups they belong to.
- *groupfinder*, an *authorization callback* that looks up
  USERS and GROUPS.  It will be provided in a new
  *security.py* file.
- An :term:`ACL` is attached to the root resource.  Each
  row below details an :term:`ACE`:

  +----------+----------------+----------------+
  | Action   | Principal      | Permission     |
  +==========+================+================+
  | Allow    | Everyone       | View           |
  +----------+----------------+----------------+
  | Allow    | group:editors  | Edit           |
  +----------+----------------+----------------+

- Permission declarations for the views.


Summary
-------

The URL, actions, template and permission associated to each view are
listed in the following table:

+----------------------+-----------------------+-------------+------------+------------+
| URL                  |  Action               |  View       |  Template  | Permission |
|                      |                       |             |            |            |
+======================+=======================+=============+============+============+
| /                    |  Redirect to          |  view_wiki  |            |            |
|                      |  /FrontPage           |             |            |            |
+----------------------+-----------------------+-------------+------------+------------+
| /PageName            |  Display existing     |  view_page  |  view.pt   |  view      |
|                      |  page [2]_            |  [1]_       |            |            |
|                      |                       |             |            |            |
|                      |                       |             |            |            |
|                      |                       |             |            |            |
+----------------------+-----------------------+-------------+------------+------------+
| /edit_page/PageName  |  Display edit form    |  edit_page  |  edit.pt   |  edit      |
|                      |  with existing        |             |            |            |
|                      |  content.             |             |            |            |
|                      |                       |             |            |            |
|                      |  If the form was      |             |            |            |
|                      |  submitted, redirect  |             |            |            |
|                      |  to /PageName         |             |            |            |
+----------------------+-----------------------+-------------+------------+------------+
| /add_page/PageName   |  Create the page      |  add_page   |  edit.pt   |  edit      |
|                      |  *PageName* in        |             |            |            |
|                      |  storage,  display    |             |            |            |
|                      |  the edit form        |             |            |            |
|                      |  without content.     |             |            |            |
|                      |                       |             |            |            |
|                      |  If the form was      |             |            |            |
|                      |  submitted,           |             |            |            |
|                      |  redirect to          |             |            |            |
|                      |  /PageName            |             |            |            |
+----------------------+-----------------------+-------------+------------+------------+
| /login               |  Display login form.  |  login      |  login.pt  |            |
|                      |                       |             |            |            |
|                      |  If the form was      |             |            |            |
|                      |  submitted,           |             |            |            |
|                      |  authenticate.        |             |            |            |
|                      |                       |             |            |            |
|                      |  - If authentication  |             |            |            |
|                      |    successful,        |             |            |            |
|                      |    redirect to the    |             |            |            |
|                      |    page that we       |             |            |            |
|                      |    came from.         |             |            |            |
|                      |                       |             |            |            |
|                      |  - If authentication  |             |            |            |
|                      |    fails, display     |             |            |            |
|                      |    login form with    |             |            |            |
|                      |    "login failed"     |             |            |            |
|                      |    message.           |             |            |            |
|                      |                       |             |            |            |
+----------------------+-----------------------+-------------+------------+------------+
| /logout              |  Redirect to          |  logout     |            |            |
|                      |  /FrontPage           |             |            |            |
+----------------------+-----------------------+-------------+------------+------------+

.. [1] This is the default view for a Page context
       when there is no view name.
.. [2] Pyramid will return a default 404 Not Found page
       if the page *PageName* does not exist yet.
.. [3] pyramid.exceptions.Forbidden is reached when a
       user tries to invoke a view that is
       not authorized by the authorization policy.