diff options
Diffstat (limited to 'docs/tutorials/wiki/design.rst')
| -rw-r--r-- | docs/tutorials/wiki/design.rst | 151 |
1 files changed, 151 insertions, 0 deletions
diff --git a/docs/tutorials/wiki/design.rst b/docs/tutorials/wiki/design.rst new file mode 100644 index 000000000..f2a02176b --- /dev/null +++ b/docs/tutorials/wiki/design.rst @@ -0,0 +1,151 @@ +.. _wiki_design: + +====== +Design +====== + +Following is a quick overview of the design of our wiki application, to help +us understand the changes that we will be making as we work through the +tutorial. + +Overall +------- + +We choose to use :term:`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 +------ + +The root resource named ``Wiki`` will be a mapping of wiki page +names to page resources. The page resources will be instances +of a *Page* class and they store the text content. + +URLs like ``/PageName`` will be traversed using Wiki[ +*PageName* ] => page, and the context that results is the page +resource of an existing page. + +To add a page to the wiki, a new instance of the page resource +is created and its name and reference are added to the Wiki +mapping. + +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 three views to handle the normal operations of adding, +editing, and viewing wiki pages, plus one view for the wiki front page. +Two templates will be used, one for viewing, and one for both adding +and editing wiki pages. + +The default templating systems in :app:`Pyramid` are +:term:`Chameleon` and :term:`Mako`. Chameleon is a variant of +:term:`ZPT`, which is an XML-based templating language. Mako is a +non-XML-based templating language. Because we had to pick one, +we chose Chameleon for this tutorial. + +Security +-------- + +We'll eventually be adding security to our application. The components we'll +use to do this are below. + +- USERS, a dictionary mapping :term:`userids <userid>` to their + corresponding passwords. + +- GROUPS, a dictionary mapping :term:`userids <userid>` to a + list of groups to which they belong. + +- ``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 :term:`resource`. Each row below + details an :term:`ACE`: + + +----------+----------------+----------------+ + | Action | Principal | Permission | + +==========+================+================+ + | Allow | Everyone | View | + +----------+----------------+----------------+ + | Allow | group:editors | Edit | + +----------+----------------+----------------+ + +- Permission declarations are added to the views to assert the security + policies as each request is handled. + +Two additional views and one template will handle the login and +logout tasks. + +Summary +------- + +The URL, context, actions, template and permission associated to each view are +listed in the following table: + ++----------------------+-------------+-----------------+-----------------------+------------+------------+ +| URL | View | Context | Action | Template | Permission | +| | | | | | | ++======================+=============+=================+=======================+============+============+ +| / | view_wiki | Wiki | Redirect to | | | +| | | | /FrontPage | | | ++----------------------+-------------+-----------------+-----------------------+------------+------------+ +| /PageName | view_page | Page | Display existing | view.pt | view | +| | [1]_ | | page [2]_ | | | +| | | | | | | +| | | | | | | +| | | | | | | ++----------------------+-------------+-----------------+-----------------------+------------+------------+ +| /PageName/edit_page | edit_page | Page | Display edit form | edit.pt | edit | +| | | | with existing | | | +| | | | content. | | | +| | | | | | | +| | | | If the form was | | | +| | | | submitted, redirect | | | +| | | | to /PageName | | | ++----------------------+-------------+-----------------+-----------------------+------------+------------+ +| /add_page/PageName | add_page | Wiki | Create the page | edit.pt | edit | +| | | | *PageName* in | | | +| | | | storage, display | | | +| | | | the edit form | | | +| | | | without content. | | | +| | | | | | | +| | | | If the form was | | | +| | | | submitted, | | | +| | | | redirect to | | | +| | | | /PageName | | | ++----------------------+-------------+-----------------+-----------------------+------------+------------+ +| /login | login | Wiki, | Display login form. | login.pt | | +| | | Forbidden [3]_ | | | | +| | | | If the form was | | | +| | | | submitted, | | | +| | | | authenticate. | | | +| | | | | | | +| | | | - If authentication | | | +| | | | succeeds, | | | +| | | | redirect to the | | | +| | | | page that we | | | +| | | | came from. | | | +| | | | | | | +| | | | - If authentication | | | +| | | | fails, display | | | +| | | | login form with | | | +| | | | "login failed" | | | +| | | | message. | | | +| | | | | | | ++----------------------+-------------+-----------------+-----------------------+------------+------------+ +| /logout | logout | Wiki | Redirect to | | | +| | | | /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. |