Changeset 13047

Timestamp:

15 Jun 2015, 08:57:24 (9 years ago)

Author:

Henrik Bettermann

Message:

More docs.

Location:

main/waeup.kofa/trunk

Files:

• docs/source/userdocs/configuration.rst (modified) (1 diff)
• docs/source/userdocs/index.rst (modified) (1 diff)
• docs/source/userdocs/mandates.rst (added)
• docs/source/userdocs/students/browser.rst (modified) (4 diffs)
• docs/source/userdocs/testing.rst (modified) (4 diffs)
• src/waeup/kofa/students/browser.py (modified) (4 diffs)
• src/waeup/kofa/students/tests/test_browser.py (modified) (12 diffs)

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

@@ -1 +1 @@
 .. _configuration:
 
-Portal Configuration :sup:`in progress`
-***************************************
+Portal Configuration and Customization :sup:`in progress`
+*********************************************************

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

@@ -17 +17 @@
    reports
    configuration
+   mandates
    testing
    buildingdocs

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

@@ -126 +126 @@
 
 
-Ticket Redemption
------------------
+Payment Ticket Redemption
+-------------------------
 
 Directly after a student payment ticket has been paid - either by approval by an officer or by receiving a positive response from a payment gateway - the
@@ -157 +157 @@
 2. The portal can be configured (`IConfigurationContainer.carry_over`) such that failed courses are automatically carried over from one session to the next. Failed course tickets from the previous level, i.e. tickets with a score below the passmark, are collected and 'copied' into the current study level container. The attributes `automatic` and `carry_over` are set to ``True``.
 
-In most cases such an automatically created course list is not perfect or even ready for submission to the course adviser. The list must be edited according to the student's needs. Students can select further courses, which they desire to attend, and can create additional course tickets, as long as total credits do not exceed 50 (value customizable). Course tickets can also be removed. Whereas officers can remove any ticket from the list, students can remove only optional (non-mandatory) course tickets (condition customizable).
+In most cases such an automatically created course list is not perfect or even ready for submission to the course adviser. The list must be edited according to the student's needs. Students can select further courses, which they desire to attend, and can create additional course tickets, as long as the total number of credits do not exceed 50 (value customizable). Course tickets can also be removed. Whereas officers can remove any ticket from the list, students can remove only optional (non-mandatory) course tickets (condition customizable).
 
 The edit form page provides a 'Register course list' button which submits the course list to the course adviser for validation. Course advisers can't edit the registered/submitted course list, but they can validate or reject it by pressing the same-named link buttons. After pressing the 'Reject courses' button, Kofa redirects to the ContactStudentForm which can be used to inform the student about the reason of rejection. In contrast to clearance rejection, the message, which is being sent to the student by email, is neither stored in the database nor in the logfiles.
@@ -171 +171 @@
 =================================
 
-Lecturer cannot access student data directly. They don't have access to the student section. Instead, lecturers go to their course in the academic section and view or export lists of students who attended the course, either in a previous or in the current session. They do also see an 'Update scores' link button which opens the `EditScoresPage` if score editing is enabled for that department (`IDepartment.score_editing_disabled`) and `IConfigurationContainer.current_academic_session` has been set on the portal's configuration page. The page lists all students, who are attending the course in the current academic session. If score editing is allowed, the score can be entered at the end of the student line. Score editing is allowed if the student's current session corresponds with the current academic session and the student is in state 'courses validated', see method :py:meth:`CourseTicket.editable_by_lecturer<waeup.kofa.students.studylevel.CourseTicket.editable_by_lecturer>`
+Lecturers cannot access student records directly. They don't have access to the student section. Instead, lecturers go to their course in the academic section and view or export lists of students who attended the course, either in a previous or in the current session. They do also see an 'Update scores' link button which opens the `EditScoresPage` if score editing is enabled for that department (`IDepartment.score_editing_disabled`) and `IConfigurationContainer.current_academic_session` has been set on the portal's configuration page. The `EditScoresPage` lists all students, who are attending the course in the current academic session. Score editing is allowed if the student's current session corresponds with the current academic session and the student is in state 'courses validated', see method :py:meth:`CourseTicket.editable_by_lecturer<waeup.kofa.students.studylevel.CourseTicket.editable_by_lecturer>`.
 
 .. seealso::
@@ -178 +178 @@
 
 
-.. _requesting_new_password:
-
-Requesting New Password
-=======================
-
-
-.. bed_tickets:
+.. _bed_tickets:
 
 Bed Tickets
 ===========
 
+Students can obtain a bed ticket if a series of conditions is met:
+
+- The current date must be inside the booking period (between `IHostelsContainer.startdate` and `IHostelsContainer.enddate`).
+
+- The student's current session must match the accommodation session (`IHostelsContainer.accommodation_session`).
+
+- A bed ticket for the same accommodation session does not exist.
+
+- The student must be in the correct workflow state (`IHostelsContainer.accommodation_states`).
+
+- A bed type, which fits to the student, can be determined.
+
+- A bed of that type is available.
+
+- The HOS activation code is not yet used.
+
+- The student is the owner of the activation code.
+
+The customizable utility method  :py:meth:`getAccommodationDetails<waeup.kofa.students.utils.StudentsUtils.getAccommodationDetails>` composes a bed type string. Three criteria are checked: Is the student a new, a returning or a final year student? Is the student female or male? Has the student to be accommodated in a special hostel (`IHostel.special_handling`)? The resulting bed type string contains these information. Example: ``regular_female_fr`` means that a bed for a new female student in a regular hostel is wanted. If the student record allows to determine such a bed string, Kofa starts searching a proper bed space.
+
+Before Kofa searches for a free bed space, which meets the bed type criteria above, it checks if a bed space has already been allocated manually to the student. If so, then this bed is used, no matter whether the bed meets the criteria or not. (Theoretically, a male student can be accommodated in a hostel which is reserved for female students.) If no manually allocated bed space is found, Kofa searches for the right space. If bed booking is subject to a charge, Kofa also checks, if the student has entered a valid activation code, before delivering the bed coordinates to the student.
+
+
 Bed Relocation
 --------------
 
+Officers with  `ManageHostels` permission do see a 'Relocate student' link button which calls the `BedTicketRelocationPage`. This view relocates the student if student parameters or the bed type of the bed have changed. The `update` method of this view checks first if the student has a 'reserved' bed space. Students in reserved beds are never subject to relocation. It checks secondly if booking has been cancelled in the accommodation section but other bed space has been manually allocated after cancellation. Then this bed is used, no matter whether the bed meets the bed type criteria or not. If both checks are negative, Kofa searches for a free bed space, which meets the student's bed type criteria. Only if it finds a new and free bed space, it starts the relocation process by releasing the old bed, booking the new bed and designating the new bed in the bed ticket.
+
+.. seealso::
+
+  :ref:`Bed Space Booking Doctests <test_handle_accommodation>`
 
 

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

@@ -178 +178 @@
 
 The first test can be found in
-`waeup.kofa.browser.tests.test_browser.SupplementaryBrowserTests`:
-
-.. literalinclude:: ../../../src/waeup/kofa/browser/tests/test_browser.py
-   :pyobject: test_suspended_officer
-
-This test makes sure that a suspended officers can't login but see a
+`waeup.kofa.browser.tests.test_browser.SupplementaryBrowserTests`. The test makes sure that suspended officers can't login but see a
 proper warning message when trying to login. Furthermore, suspended
 officer accounts are clearly marked and a warning message shows up
@@ -189 +184 @@
 <officers>`.
 
+.. literalinclude:: ../../../src/waeup/kofa/browser/tests/test_browser.py
+   :pyobject: test_suspended_officer
+
 
 .. _test_handle_clearance:
 
-Handle Clearance by Clearance Officer
--------------------------------------
-
-This test can be found in
-`waeup.kofa.students.tests.test_browser.OfficerUITests`:
+Handling Clearance by Clearance Officer
+---------------------------------------
+
+This test can be found in
+`waeup.kofa.students.tests.test_browser.OfficerUITests`. The corresponding use
+case is partly described :ref:`elsewhere <rejecting_clearance>`.
 
 .. literalinclude:: ../../../src/waeup/kofa/students/tests/test_browser.py
@@ -204 +203 @@
 .. _test_handle_courses:
 
-Handle Course List Validation by Course Adviser
------------------------------------------------
-
-This test can be found in
-`waeup.kofa.students.tests.test_browser.OfficerUITests`:
+Handling Course List Validation by Course Adviser
+-------------------------------------------------
+
+This test can be found in
+`waeup.kofa.students.tests.test_browser.OfficerUITests`. The corresponding use
+case is described :ref:`elsewhere <course_registration>`.
 
 .. literalinclude:: ../../../src/waeup/kofa/students/tests/test_browser.py
@@ -220 +220 @@
 
 This test can be found in
-`waeup.kofa.students.tests.test_browser.OfficerUITests`:
+`waeup.kofa.students.tests.test_browser.OfficerUITests`. The corresponding use
+case is described :ref:`elsewhere <batch_editing_scores>`.
 
 .. literalinclude:: ../../../src/waeup/kofa/students/tests/test_browser.py
    :pyobject: test_handle_courses_by_lecturer
+
+
+.. _test_handle_accommodation:
+
+Bed Space Booking
+-----------------
+
+This test can be found in
+`waeup.kofa.students.tests.test_browser.OfficerUITests`. The corresponding use
+case is described :ref:`elsewhere <bed_tickets>`.
+
+.. literalinclude:: ../../../src/waeup/kofa/students/tests/test_browser.py
+   :pyobject: test_student_accommodation

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

@@ -2052 +2052 @@
                 self.flash(_('System error: Please contact the adminsitrator.'),
                            type="danger")
-                self.context.writeLogMessage(self, 'fatal error: %s' % bed.bed_id)
+                self.context.writeLogMessage(
+                    self, 'fatal error: %s' % bed.bed_id)
                 return
         else:
@@ -2063 +2064 @@
                 students_utils = getUtility(IStudentsUtils)
                 bed = students_utils.selectBed(available_beds)
-                # Safety belt for paranoids: Does this bed really exist in portal?
+                # Safety belt for paranoids: Does this bed really exist
+                # in portal?
                 # XXX: Can be remove if nobody complains.
                 if bed.__parent__.__parent__ is None:
-                    self.flash(_('System error: Please contact the adminsitrator.'),
-                               type="warning")
-                    self.context.writeLogMessage(self, 'fatal error: %s' % bed.bed_id)
+                    self.flash(_(
+                        'System error: Please contact the adminsitrator.'),
+                        type="warning")
+                    self.context.writeLogMessage(
+                        self, 'fatal error: %s' % bed.bed_id)
                     return
                 bed.bookBed(student.student_id)
@@ -2219 +2223 @@
             self.context.bed.owner = NOT_OCCUPIED
             notify(grok.ObjectModifiedEvent(self.context.bed))
-        # Alocate new bed
+        # Designate new bed in ticket
         self.context.bed_type = acc_details['bt']
         self.context.bed = new_bed
@@ -2788 +2792 @@
 
 class StudentRequestPasswordPage(KofaAddFormPage):
-    """Captcha'd registration page for applicants.
+    """Captcha'd request password page for students.
     """
     grok.name('requestpw')

main/waeup.kofa/trunk/src/waeup/kofa/students/tests/test_browser.py

@@ -1476 +1476 @@
             '...<div>Academics Officer (view only)</div>...',
             self.browser.contents)
-        #self.assertMatches(
-        #    '...<div>Students Officer (view only)</div>...',
-        #    self.browser.contents)
         # But not his local role ...
         self.assertFalse('Clearance Officer' in self.browser.contents)
@@ -1484 +1481 @@
         # has changed
         notify(LocalRoleSetEvent(
-            self.department, 'waeup.local.ClearanceOfficer', 'mrclear', granted=True))
+            self.department, 'waeup.local.ClearanceOfficer', 'mrclear',
+            granted=True))
         self.browser.open('http://localhost/app/users/mrclear/my_roles')
         self.assertTrue('Clearance Officer' in self.browser.contents)
@@ -1525 +1523 @@
             self.browser.url, self.student_path + '/reject_clearance')
         # Type comment why
-        self.browser.getControl(name="form.officer_comment").value = """Dear Student,
-You did not fill properly.
-"""
+        self.browser.getControl(name="form.officer_comment").value = (
+            'Dear Student,\n'
+            'You did not fill properly.')
         self.browser.getControl("Save comment").click()
         self.assertTrue('Clearance has been annulled' in self.browser.contents)
         url = ('http://localhost/app/students/K1000000/'
               'contactstudent?body=Dear+Student%2C%0AYou+did+not+fill+properly.'
-              '%0A&subject=Clearance+has+been+annulled.')
+              '&subject=Clearance+has+been+annulled.')
         # CO does now see the prefilled contact form and can send a message
         self.assertEqual(self.browser.url, url)
@@ -1545 +1543 @@
         # The comment has been stored ...
         self.assertEqual(self.student.officer_comment,
-            u'Dear Student,\nYou did not fill properly.\n')
+            u'Dear Student,\nYou did not fill properly.')
         # ... and logged
         logfile = os.path.join(
@@ -1553 +1551 @@
             'INFO - mrclear - students.browser.StudentRejectClearancePage - '
             'K1000000 - comment: Dear Student,<br>You did not fill '
-            'properly.<br>\n' in logcontent)
+            'properly.\n' in logcontent)
         self.browser.open(self.history_path)
         self.assertTrue("Reset to 'clearance started' by My Public Name" in
@@ -1601 +1599 @@
         # Additional setups according to test above
         notify(LocalRoleSetEvent(
-            self.department, 'waeup.local.ClearanceOfficer', 'mrclear', granted=True))
+            self.department, 'waeup.local.ClearanceOfficer', 'mrclear',
+            granted=True))
         self.app['configuration']['2004'].clearance_enabled = True
         IWorkflowState(self.student).setState('clearance requested')
@@ -2971 +2970 @@
 
     def test_student_accommodation(self):
-        # Login
         self.browser.open(self.login_path)
         self.browser.getControl(name="form.login").value = self.student_id
         self.browser.getControl(name="form.password").value = 'spwd'
         self.browser.getControl("Login").click()
-
         # Students can add online booking fee payment tickets and open the
         # callback view (see test_manage_payments)
@@ -2993 +2990 @@
         parts = pin.split('-')[1:]
         sfeseries, sfenumber = parts
-
         # Students can use HOS code and book a bed space with it ...
         self.browser.open(self.acco_path)
@@ -3029 +3025 @@
         self.assertMatches('...Hall 1, Block A, Room 101, Bed A...',
                            self.browser.contents)
-
         # Bed has been allocated
         bed = self.app['hostels']['hall-1']['hall-1_A_101_A']
         self.assertTrue(bed.owner == self.student_id)
-
         # BedTicketAddPage is now blocked
         self.browser.getLink("Book accommodation").click()
         self.assertMatches('...You already booked a bed space...',
             self.browser.contents)
-
         # The bed ticket displays the data correctly
         self.browser.open(self.acco_path + '/2004')
@@ -3046 +3039 @@
         self.assertMatches('...regular_male_fr...', self.browser.contents)
         self.assertMatches('...%s...' % pin, self.browser.contents)
-
         # Students can open the pdf slip
         self.browser.open(self.browser.url + '/bed_allocation_slip.pdf')
         self.assertEqual(self.browser.headers['Status'], '200 Ok')
         self.assertEqual(self.browser.headers['Content-Type'], 'application/pdf')
-
         # Students can't relocate themselves
         self.assertFalse('Relocate' in self.browser.contents)
@@ -3057 +3048 @@
         self.assertRaises(
             Unauthorized, self.browser.open, relocate_path)
-
         # Students can't the Remove button and check boxes
         self.browser.open(self.acco_path)
         self.assertFalse('Remove' in self.browser.contents)
         self.assertFalse('val_id' in self.browser.contents)
-
         # Students can pay maintenance fee now
         self.browser.open(self.payments_path)
@@ -3070 +3059 @@
         self.assertMatches('...Payment ticket created...',
                            self.browser.contents)
-
         ctrl = self.browser.getControl(name='val_id')
         value = ctrl.options[0]