Changeset 13026 for main/waeup.kofa/trunk

Timestamp:

2 Jun 2015, 12:15:52 (9 years ago)

Author:

Henrik Bettermann

Message:

More docs.

Location:

main/waeup.kofa/trunk

Files:

• docs/source/userdocs/academics.rst (modified) (2 diffs)
• docs/source/userdocs/students/browser.rst (modified) (2 diffs)
• docs/source/userdocs/students/interfaces.rst (modified) (1 diff)
• docs/source/userdocs/students/workflow.rst (modified) (1 diff)
• src/waeup/kofa/students/permissions.py (modified) (2 diffs)
• src/waeup/kofa/students/student.py (modified) (1 diff)

main/waeup.kofa/trunk/docs/source/userdocs/academics.rst

@@ -23 +23 @@
 hierarchical structure as described above. Technically speaking, the
 academic section is a container of type `FacultiesContainer` with id
-``academics`` which contains faculty sub-containers. They again
-contain department sub-objects and so on. This leads to a
+``academics`` which contains faculty subcontainers. They again
+contain department subobjects and so on. This leads to a
 :ref:`treelike storage of objects <object_database>`::
 
@@ -83 +83 @@
 the user to believe that `certificates` and `courses` are the ids of
 objects stored inside a department container. De facto they are not.
-However, it doesn't matter if we store a sub-object 'in' or 'at' a
+However, it doesn't matter if we store a subobject 'in' or 'at' a
 parent object. The result is exactly the same: :ref:`a hierarchical,
 treelike storage of objects <object_database>` (see also diagram above).

main/waeup.kofa/trunk/docs/source/userdocs/students/browser.rst

@@ -4 +4 @@
 ============================
 
-The reader may ask: How do officers and students browse the portal? Where are the step-by-step operating instructions on how to use Kofa? We are always tempted to answer: The menu navigation should be self-explanatory and it's quite easy to follow the menu prompts. For the students section this answer seems a bit over the top. We must indeed describe some browser pages and what their clickable actions are doing with the data. The reason is, that a lot of Kofa's functionality is embedded in view and utility methods and not only provided by the functionality of content classes as described above.
+The reader may ask: How do officers and students browse the portal? Where are the step-by-step operating instructions on how to use Kofa? We are always tempted to answer: The menu navigation should be self-explanatory and it's quite easy to follow the menu prompts. For the students section this answer seems a bit over the top. We must indeed describe some browser pages and what their clickable actions are doing with the data. The reason is, that a lot of Kofa's functionality is embedded in view and utility methods and not only provided by the functionality of content components as described above.
 
 Page Layout
 ===========
 
-Kofa makes use of two different `Bootstrap`_ layouts. Anonymous users, students and applicants do see a single-column theme with only a static top navigation bar. Students can navigate to the various pages of their record by pulling down the 'My Data' in the navigation bar.
+Kofa makes use of two different `Bootstrap`_ layouts. Anonymous users, students and applicants do see a single-column theme with only a static top navigation bar. Students can navigate to the various display pages of their record by pulling down the 'My Data' in the navigation bar.
+
+Officers see a double-column theme after logging in. The left column contains a box which contains links to the user's preferences (My Preferences) and roles (My Roles). It also contains links to the various sections of Kofa depending on the permissions the officer has has obtained. Possible sections are: 'Portal Configuration', 'Officers', 'Data Center', 'Reports' and 'Access Codes'. A second box shows up in the left column when the officer accesses a student record. This box gives direct access to the display pages of a student record.
+
+Manage and Edit Pages
+=====================
+
+Pages, or more precisely web pages, are browser views which render (produce) HTML or PDF code to be displayed in a web browser or a pdf reader respectively. Views are dealing with request and response objects. In Kofa most pages are form pages which means they are views on data. These pages are either used to display, edit or add persistant data. Thus we can further distinguish display, edit and add form pages. Kofa is using the `Zope Formlib`_ package to auto-generate these forms.
+
+.. note::
+
+  Briefly, Zope Formlib is wedded to `Zope Schema`_, it provides display and input widgets (= views) for the fields defined in the Zope Schema package. Auto-generation is done with `grok.AutoFields` which takes the fields declared in an interface and renders display or input widgets according to the schema declaration for display or edit forms respectively.
+
+Whereas display and add form pages are usually shared by officers and students, edit form pages are not. Students are not allowed to edit all of their data all the time. Edit access is restricted by workflow states or other conditions. Officers' access is much less restricted and we therefore speak of 'managing' instead of 'editing' data. In most cases, Kofa uses two different form pages which require different permissions: An `EditFormPage` requires the :py:class:`HandleStudent<waeup.kofa.students.permissions.HandleStudent>` permission and a `ManageFormPage` requires the :py:class:`ManageStudent<waeup.kofa.students.permissions.ManageStudent>` permission.
 
 Action Buttons
 ==============
 
-Managing or Editing Student Pages
-=================================
+There are two kinds of action buttons which appear on pages: 
 
-Loging in as Student
-====================
+-  **Link Buttons** appear on top of the page above the page
+   title and are decorated with an icon. These
+   :py:class:`action
+   buttons<waeup.kofa.browser.viewlets.ActionButton>` have a
+   link target which means they usually refer to another Kofa
+   page and are sending GET requests to open the page.
+
+-  **Form Buttons** are submit buttons which appear below a form.
+   They are HTML form actions which submit data by sending a
+   POST request back to the form page. A form page method is
+   called and processes the data or simply redirects to
+   another Kofa page.
+
+Logging in as Student
+=====================
+
+Officers with :py:class:`LoginAsStudent<waeup.kofa.students.permissions.LoginAsStudent>` permission do see a 'Login as student' button on student display pages, which redirects to a page where a temporary student password can be set by clicking a 'Set password now' form button. The temporary password is valid for 10 minutes. During this period the student can't login. The officer is being redirected to a login page which allows to directly login as student with pre-filled temporary credentials. The second page is to avoid that officers must remember the student credentials, logout from their own account and manually login as student via the regular login page. After 10 minutes the officer is automatically thrown out and the student is able to login again (if the officer hasn't changed the password). Attention: When logging in as student, the officer really impersonates the student. All actions are logged with the student id and not with the officer's user id. However, start of student impersonation is also logged, so that officers can be identified and fraudulent use can be discovered.
 
 Rejecting Clearance
@@ -48 +75 @@
 
 .. _bootstrap: http://getbootstrap.com/
+
+.. _zope schema: http://docs.zope.org/zope.schema
+
+.. _zope formlib: http://bluebream.zope.org/doc/1.0/manual/schema.html#auto-generated-forms-using-the-forms-package

main/waeup.kofa/trunk/docs/source/userdocs/students/interfaces.rst

@@ -6 +6 @@
 The `Student` class is a container class which means, there are not
 only attributes describing the student entity but also content. Each
-student container contains exactly three sub-containers:
+student container contains exactly three subcontainers:
 ``studycourse`` (instance of `StudentStudyCourse`), ``payments``
 (instance of `StudentPaymentsContainer`) and ``accommodation``
 (instance of `StudentAccommodation`). The purposes of them are
-described further below.
+described further below. The student container with all its
+subcontainers and subobjects is called **student record**.
 
 Let's talk about the attributes and methods belonging to the

main/waeup.kofa/trunk/docs/source/userdocs/students/workflow.rst

@@ -100 +100 @@
 the necessary course tickets and finally registers the list **(g)**.
 The student's course adviser subsequently validates the list **(i)**,
- or rejects the course registration request **(-g)** so that the
+or rejects the course registration request **(-g)** so that the
 student has to register again. Even after validation there is an
 option to annul the already validated course list **(-m)** so that

main/waeup.kofa/trunk/src/waeup/kofa/students/permissions.py

@@ -64 +64 @@
 class ManageStudent(grok.Permission):
     """The ManageStudent permission allows to edit the data.
-    This permission is meant for clearance officers.
+    This permission is meant for students officers.
     """
     grok.name('waeup.manageStudent')
@@ -70 +70 @@
 class ClearStudent(grok.Permission):
     """The ClearStudent permission is needed to clear students
-    or to reject clearance. This permission is meant for course advisers.
+    or to reject clearance. This permission is meant for clearance officers.
     """
     grok.name('waeup.clearStudent')

main/waeup.kofa/trunk/src/waeup/kofa/students/student.py

@@ -71 +71 @@
         """Set a temporary password (LDAP-compatible) SSHA encoded for
         officers.
-
         """
         passwordmanager = getUtility(IPasswordManager, 'SSHA')