source: main/waeup.kofa/trunk/docs/source/userdocs/browsing.rst @ 13088

Last change on this file since 13088 was 13084, checked in by Henrik Bettermann, 9 years ago

Add browsing chapter and restructure documentation.

File size: 4.6 KB
Line 
1.. _browsing_kofa:
2
3Browsing Kofa
4*************
5
6The reader may ask: How do officers, applicants and students browse
7the portal? Where are the step-by-step operating instructions on how
8to use Kofa? We are always tempted to answer: The menu navigation
9should be self-explanatory and it's quite easy to follow the menu
10prompts or flash messages which appear above page titles in a green,
11yellow or red box. This answer seems a bit over the top. We must
12indeed describe some browser pages and what their clickable actions
13are doing with the data. The reason is, that a lot of Kofa's
14functionality is embedded in view and utility methods and not only
15provided by the functionality of content components. In the
16following, functionality of pages is described in subchapters called
17'Browser Pages'.
18
19
20.. _page_layout:
21
22Page Layout
23===========
24
25Kofa makes use of two different `Bootstrap`_ layouts. Anonymous
26users, students and applicants do see a single-column theme with
27only a static top navigation bar. Students can navigate to the
28various display form pages of their record by pulling down the 'My
29Data' tab in the navigation bar.
30
31Officers see a double-column theme after logging in. The left column
32contains a box which contains links to the user's preferences (My
33Preferences) and roles (My Roles). It also contains links to the
34various sections of Kofa depending on the permissions the officer
35has has obtained. Possible sections are: 'Portal Configuration',
36'Officers', 'Data Center', 'Reports' and 'Access Codes'. A second
37box shows up in the left column when the officer accesses an
38applicant or student record. This box gives direct access to the
39pages of an applicant or student record respectively.
40
41
42
43.. _navigation_bar:
44
45Navigation Bar
46==============
47
48
49.. _manage_edit_pages:
50
51Views, Pages and Form Pages
52===========================
53
54Views are dealing with request and response objects. Usually a view
55renders (produces) HTML or PDF code to be displayed in a web browser
56or a pdf reader respectively. Very often a view only redirects to
57another view or page and does not render code by itself.
58Views, which render pdf code, are called pdf slips in Kofa.
59
60Kofa pages are 'layout-aware' browser views, which means they know
61about the global page layout and render content inside it.
62
63In Kofa most pages are form pages which means they are layout-aware
64views on data. These pages are either used to submit data (simple form
65page), or to display, edit or add persistant data. The latter three
66are called display, edit or add form pages respectively. Kofa is
67using the `Zope Formlib`_ package to auto-generate these forms.
68
69.. note::
70
71  Briefly, Zope Formlib is wedded to `Zope Schema`_, it provides
72  display and input widgets (= views) for the fields defined in the
73  Zope Schema package. Auto-generation is done with `grok.AutoFields`
74  which takes the fields, declared in an interface, and renders
75  display or input widgets, according to the schema declaration, for
76  display or edit forms respectively.
77
78Whereas display and add form pages are usually shared by officers
79and students, edit form pages are not. Applicants and students are
80not allowed to edit all of their data all the time. Edit access is
81restricted by workflow states or other conditions. Officers' access
82is much less restricted, and we therefore speak of 'managing'
83instead of 'editing' data. In most cases, Kofa uses two different
84form pages which require different permissions: An `EditFormPage`
85requires the
86:py:class:`HandleApplication<waeup.kofa.applicants.permissions.HandleApplication>`
87/
88:py:class:`HandleStudent<waeup.kofa.students.permissions.HandleStudent>`
89permission and a `ManageFormPage` requires the
90:py:class:`ManageStudent<waeup.kofa.students.permissions.ManageStudent>`
91permission.
92
93
94
95.. _action_buttons:
96
97Action Buttons
98==============
99
100There are two kinds of action buttons which appear on pages:
101
102-  **Link Buttons** appear on top of the page above the page
103   title and are decorated with an icon. These
104   :py:class:`action
105   buttons<waeup.kofa.browser.viewlets.ActionButton>` have a
106   link target which means they usually refer to another Kofa
107   page and are sending GET requests to open the page.
108
109-  **Form Buttons** are submit buttons which appear below a form.
110   They are HTML form actions which submit data by sending a
111   POST request back to the form page. A form page method is
112   called and processes the data or simply redirects to
113   another Kofa page.
114
115
116.. _bootstrap: http://getbootstrap.com/
117
118.. _zope schema: http://docs.zope.org/zope.schema
119
120.. _zope formlib: http://bluebream.zope.org/doc/1.0/manual/schema.html#auto-generated-forms-using-the-forms-package
Note: See TracBrowser for help on using the repository browser.