From bb754144b1c0d3c75156385ea8c6e20ddda6d430 Mon Sep 17 00:00:00 2001 From: Patricio Paez Date: Mon, 12 Mar 2012 14:32:54 -0700 Subject: Added the Design chapter on both wiki tutorials --- docs/tutorials/wiki/design.rst | 134 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 134 insertions(+) create mode 100644 docs/tutorials/wiki/design.rst (limited to 'docs/tutorials/wiki/design.rst') diff --git a/docs/tutorials/wiki/design.rst b/docs/tutorials/wiki/design.rst new file mode 100644 index 000000000..ea7076f60 --- /dev/null +++ b/docs/tutorials/wiki/design.rst @@ -0,0 +1,134 @@ +========== +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 +------ + +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 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, 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 | | | +| | | | successful, | | | +| | | | 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. -- cgit v1.2.3 From 2f2c4811db0de95c8358f733e013c91b245995e5 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 17 Mar 2012 14:15:09 -0400 Subject: normalize zodb tut design doc with text from sqla design doc --- docs/tutorials/wiki/design.rst | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) (limited to 'docs/tutorials/wiki/design.rst') diff --git a/docs/tutorials/wiki/design.rst b/docs/tutorials/wiki/design.rst index ea7076f60..1cf70b8ac 100644 --- a/docs/tutorials/wiki/design.rst +++ b/docs/tutorials/wiki/design.rst @@ -43,13 +43,19 @@ will handle the login and logout tasks related to security. Security -------- +We'll eventually be adding security to our application. The components we'll +use to do this are below. + - 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`: @@ -61,7 +67,8 @@ Security | Allow | group:editors | Edit | +----------+----------------+----------------+ -- Permission declarations for the views. +- Permission declarations are added to the views to assert the security + policies as each request is handled. Summary -- cgit v1.2.3 From 0dc5716037d9ba5ffffbddf2ade893cc55b7ddd4 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 17 Mar 2012 14:15:52 -0400 Subject: normalize zodb tut design doc with text from sqla design doc --- docs/tutorials/wiki/design.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/tutorials/wiki/design.rst') diff --git a/docs/tutorials/wiki/design.rst b/docs/tutorials/wiki/design.rst index 1cf70b8ac..2b613377a 100644 --- a/docs/tutorials/wiki/design.rst +++ b/docs/tutorials/wiki/design.rst @@ -4,14 +4,14 @@ 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. +default files generated by the ``zodb`` 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 +widely used ``docutils`` Python module. We will add this module in the dependency list on the project ``setup.py`` file. Models -- cgit v1.2.3 From f97aa6332c08d5edb35665a7afda2aefd98f662b Mon Sep 17 00:00:00 2001 From: Patricio Paez Date: Fri, 13 Apr 2012 13:10:00 -0500 Subject: Simplify the introduction - Moved the selection of the templates to the Design chapter - Improved the Views section in the Design chapter - Normalize in both tutorials --- docs/tutorials/wiki/design.rst | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) (limited to 'docs/tutorials/wiki/design.rst') diff --git a/docs/tutorials/wiki/design.rst b/docs/tutorials/wiki/design.rst index 2b613377a..c94612fb1 100644 --- a/docs/tutorials/wiki/design.rst +++ b/docs/tutorials/wiki/design.rst @@ -36,9 +36,16 @@ 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. +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 for 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 -------- @@ -52,11 +59,11 @@ use to do this are below. - GROUPS, a dictionary mapping user names to a list of groups they belong to. -- *groupfinder*, an *authorization callback* that looks up +- ``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 +- An :term:`ACL` is attached to the root :term:`resource`. Each row below details an :term:`ACE`: +----------+----------------+----------------+ @@ -70,6 +77,8 @@ use to do this are below. - 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 ------- -- cgit v1.2.3 From 57a98dc3801415a25e4a7be841b7fba358214c2d Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Tue, 1 Jan 2013 16:39:20 +0200 Subject: "usernames" is a more correct term --- docs/tutorials/wiki/design.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/tutorials/wiki/design.rst') diff --git a/docs/tutorials/wiki/design.rst b/docs/tutorials/wiki/design.rst index c94612fb1..b44ccb10e 100644 --- a/docs/tutorials/wiki/design.rst +++ b/docs/tutorials/wiki/design.rst @@ -53,10 +53,10 @@ Security We'll eventually be adding security to our application. The components we'll use to do this are below. -- USERS, a dictionary mapping users names to their +- USERS, a dictionary mapping usernames to their corresponding passwords. -- GROUPS, a dictionary mapping user names to a +- GROUPS, a dictionary mapping usernames to a list of groups they belong to. - ``groupfinder``, an *authorization callback* that looks up -- cgit v1.2.3 From 3ead59ea06ee933f4729f6b021d886be53f655be Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 21 Jan 2013 02:21:18 -0800 Subject: minor grammar, spelling --- docs/tutorials/wiki/design.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/tutorials/wiki/design.rst') diff --git a/docs/tutorials/wiki/design.rst b/docs/tutorials/wiki/design.rst index b44ccb10e..eb785dd1c 100644 --- a/docs/tutorials/wiki/design.rst +++ b/docs/tutorials/wiki/design.rst @@ -4,7 +4,7 @@ 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 ``zodb`` scafffold. +default files generated by the ``zodb`` scaffold. Overall ------- @@ -37,8 +37,8 @@ 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 for 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 @@ -57,7 +57,7 @@ use to do this are below. corresponding passwords. - GROUPS, a dictionary mapping usernames to a - list of groups they belong to. + list of groups to which they belong to. - ``groupfinder``, an *authorization callback* that looks up USERS and GROUPS. It will be provided in a new -- cgit v1.2.3 From dc324784193a577bc039dcddb0651ef5ec9e6f57 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Tue, 12 Aug 2014 22:12:25 -0500 Subject: Docs: Make "userid" link to the glossary term. --- docs/tutorials/wiki/design.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/tutorials/wiki/design.rst') diff --git a/docs/tutorials/wiki/design.rst b/docs/tutorials/wiki/design.rst index eb785dd1c..28380bd66 100644 --- a/docs/tutorials/wiki/design.rst +++ b/docs/tutorials/wiki/design.rst @@ -53,10 +53,10 @@ Security We'll eventually be adding security to our application. The components we'll use to do this are below. -- USERS, a dictionary mapping usernames to their +- USERS, a dictionary mapping :term:`userids ` to their corresponding passwords. -- GROUPS, a dictionary mapping usernames to a +- GROUPS, a dictionary mapping :term:`userids ` to a list of groups to which they belong to. - ``groupfinder``, an *authorization callback* that looks up -- cgit v1.2.3 From 3e6b601d9bc557b5b698d5fd4d6eb20b151a424f Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 25 May 2015 13:53:05 -0700 Subject: cherry pick from 1.5-branch --- docs/tutorials/wiki/design.rst | 37 ++++++++++++++++++------------------- 1 file changed, 18 insertions(+), 19 deletions(-) (limited to 'docs/tutorials/wiki/design.rst') diff --git a/docs/tutorials/wiki/design.rst b/docs/tutorials/wiki/design.rst index 28380bd66..49c30d29a 100644 --- a/docs/tutorials/wiki/design.rst +++ b/docs/tutorials/wiki/design.rst @@ -2,22 +2,22 @@ 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 ``zodb`` scaffold. +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 ``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. +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 +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. @@ -29,9 +29,9 @@ 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. +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 ----- @@ -57,14 +57,13 @@ use to do this are below. corresponding passwords. - GROUPS, a dictionary mapping :term:`userids ` to a - list of groups to which they belong to. + 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. +- ``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`: +- An :term:`ACL` is attached to the root :term:`resource`. Each row below + details an :term:`ACE`: +----------+----------------+----------------+ | Action | Principal | Permission | @@ -125,7 +124,7 @@ listed in the following table: | | | | authenticate. | | | | | | | | | | | | | | - If authentication | | | -| | | | successful, | | | +| | | | succeeds, | | | | | | | redirect to the | | | | | | | page that we | | | | | | | came from. | | | @@ -145,6 +144,6 @@ listed in the following table: 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 +.. [3] ``pyramid.exceptions.Forbidden`` is reached when a user tries to invoke a view that is not authorized by the authorization policy. -- cgit v1.2.3 From 8d2a2b967ff912aa0b8e74128cf2b5473d6db44a Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 29 Jan 2016 23:20:25 -0800 Subject: fix heading under/overlines for rst syntax (cherry picked from commit 60b74ee) --- docs/tutorials/wiki/design.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/tutorials/wiki/design.rst') diff --git a/docs/tutorials/wiki/design.rst b/docs/tutorials/wiki/design.rst index 49c30d29a..46c2a2f30 100644 --- a/docs/tutorials/wiki/design.rst +++ b/docs/tutorials/wiki/design.rst @@ -1,6 +1,6 @@ -========== +====== 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 -- cgit v1.2.3 From 93a7a14d0abf0a7c1659275dc78ebc15247ca893 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 9 Apr 2016 15:17:52 -0700 Subject: - fix traversal tutorial reference - add intersphinx targets to wiki/* --- docs/tutorials/wiki/design.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/tutorials/wiki/design.rst') diff --git a/docs/tutorials/wiki/design.rst b/docs/tutorials/wiki/design.rst index 46c2a2f30..f2a02176b 100644 --- a/docs/tutorials/wiki/design.rst +++ b/docs/tutorials/wiki/design.rst @@ -1,3 +1,5 @@ +.. _wiki_design: + ====== Design ====== -- cgit v1.2.3