Changeset 13003 for main/waeup.kofa/trunk/docs/source

Timestamp:

27 May 2015, 07:20:57 (10 years ago)

Author:

Henrik Bettermann

Message:

More docs and necessary adjustment of code.

Location:

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

Files:

• datacenter/import_processors.rst (modified) (1 diff)
• students.rst (modified) (6 diffs)

main/waeup.kofa/trunk/docs/source/userdocs/datacenter/import_processors.rst

@@ -136 +136 @@
   verdicts have to be set or workflow transitions have to be triggered.
 
+.. _course_ticket_processor:
+
 Course Ticket Processor
 -----------------------

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

@@ -4 +4 @@
 **********************************
 
-'Student' is a multi-purpose term in Kofa which may lead to some misconceptions. First of all 'Student' is a Python/Grok container class and student objects are the instances of this class. Sometimes we are sluggish when talking about 'creating students' and actually mean: 'creating student container objects and storing the objects (persistently) in the ``students`` container'. The latter is the parent container for all students in the portal.
+'Student' is a multi-purpose term in Kofa which may lead to some misconceptions. First of all, 'Student' is a Python/Grok container class and student objects are the instances of this class. Sometimes we are sluggish when talking about 'creating students' and actually mean: 'creating student container objects and storing the objects (persistently) in the ``students`` container'. The latter is the parent container for all students in the portal.
 
 The :ref:`treelike storage of objects <object_database>` in the student section can be figured as follows::
@@ -57 +57 @@
    :pyobject: IStudentBase
 
-The **first part** of the interface lists attributes. Except for the first two (`password` and `temp_password`) they are all read-only property attributes, i.e. attributes with a getter method only. These properties are computed dynamically and can't be set. Most of them return data derived from the ``studycourse`` subobject.
+The **first part** of the interface lists attributes. Except for the last two attributes (`password` and `temp_password`) they are all read-only property attributes, i.e. attributes with a getter method only. These properties are computed dynamically and can't be set. Most of them return data derived from the ``studycourse`` subobject.
 
 The **second part** of the interface specifies the schema fields
@@ -71 +71 @@
   **Vocabularies and sources** are very similar. The latter is a newer concept of producing choices and considered to replace vocabularies. In Kofa we are using both. Common to both is that a set of values is accompanied by a user-friendly title, which is displayed on pages (e.g. in select boxes) instead of a less informative value token or even a cryptic representation of a persistent value object. In most cases we have a token-title pair which perfectly describes the values of a source or a vocabulary. The tokens are being sent in forms or imported by batch processors.
 
-  **Token-title pairs** of most (non-database-dependent) sources and vocabularies of the Kofa base package can be viewed `here <http://kofa-demo.waeup.org/sources>`_.
+  See `token-title pairs <http://kofa-demo.waeup.org/sources>`_ of most (non-database-dependent) sources and vocabularies in the Kofa base package.
 
 The **third part** of the interface lists the methods which can be applied to student objects.
@@ -107 +107 @@
 Kofa provides a mechanism which ensures that personal data are being kept up to date. Students are regularly requested to update the personal data directly after login. The personal data expire 180 days after saving the data for the last time which is stored in the `personal_updated` attribute. Then the `personal_data_expired` property returns ``True`` and the student is redirected to the personal data edit page when logging in.
 
+`IStudentNavigation`
+--------------------
+
+See docstring.
+
+.. literalinclude:: ../../../src/waeup/kofa/students/interfaces.py
+   :pyobject: IStudentNavigation
+
 Student Study Courses
 =====================
 
-All data related to an individual course of study are stored with the ``studycourse`` object. This container object is an instance of the `StudentStudyCourse` class which implements `waeup.kofa.students.interfaces.IStudentStudyCourse`.
+All data related to an individual course of study are stored with the ``studycourse`` object. This container object is an instance of the `StudentStudyCourse` class which implements `waeup.kofa.students.interfaces.IStudentStudyCourse`, `waeup.kofa.students.interfaces.IStudentNavigation` and `waeup.kofa.students.interfaces.IStudentStudyCourseTranscript`. The latter does not add further behaviour to our classes but is needed for transcript pages only. It is not described in the user handbook.
 
 `IStudentStudyCourse`
@@ -128 +136 @@
 What is a verdict? A verdict is the individual judgement of a jury (senate in Nigeria) at the end of each academic session. The jury's verdict tells the portal, if the student has successfully completed an academic session or not. Depending on the verdict, the student will be either allowed to proceed to the next study level or forced to repeat the current level. Without a verdict, the student gets stuck and cannot even pay school fees for the next academic year. This will be further exlplained in the workflow section below.
 
-`StudentStudyCourse` is a container class. Study courses contain `StudentStudyLevel` instances which implement `waeup.kofa.students.interfaces.IStudentStudyLevel`.
+`StudentStudyCourse` is a container class. Study courses contain `StudentStudyLevel` instances which implement `waeup.kofa.students.interfaces.IStudentStudyLevel` and also `waeup.kofa.students.interfaces.IStudentNavigation`, see above.
 
 `IStudentStudyLevel`
 --------------------
 
-`StudentStudyLevel` instances contain information about the study progress achieved at that level. In Kofa study levels range from 100 to 900. There are two additional levels: a pre-studies level (10) and a special postgraduate level (999). There are also two probation levels per regular study level. Level 120, for instance, means level 100 on second probation. The complete numbering of study levels can be viewed `here <https://kofa-demo.waeup.org/sources#collapseStudyLevels>`_.
+`StudentStudyLevel` instances contain information about the study progress achieved at that level. In Kofa study levels range from 100 to 900. There are two additional levels: a pre-studies level (10) and a special postgraduate level (999). There are also two probation levels per regular study level. Level 120, for instance, means level 100 on second probation. See `complete numbering of study levels <https://kofa-demo.waeup.org/sources#collapseStudyLevels>`_ in the base package.
 
 `StudentStudyLevel` instances are container objects which contain course tickets. We therefore sometimes speak of a level course list instead of a study level. The study level stores and provides the information when (`validation_date`) and by whom (`validated_by`) the course list was validated, in which session the level was taken (`level_session`) and which verdict the student finally obtained.
@@ -140 +148 @@
    :pyobject: IStudentStudyLevel
 
-`StudentStudyLevel` instances also compute some statistical values on the fly to give an overview of the courses taken. These read-only property attributes are: `number_of_tickets`, `passed_params`, `gpa_params`, `gpa_params_rectified`, `cumulative_params`, `total_credits` and `gpa`. The attentive reader may wonder why the latter two are not listed in the attributes section of the interface, but as read-only schema fields further below. This is a trick which we used to properly display these fields on some form pages and pdf slips. However, the `attrs_to_fields` function explicitly excludes them when starting the portal, so that these fields are not used for persistent storage of same-named attributes in the database.
+`StudentStudyLevel` instances also compute some statistics on the fly to give an overview of the courses taken. These read-only property attributes are: `number_of_tickets`, `passed_params`, `gpa_params`, `gpa_params_rectified`, `cumulative_params`, `total_credits` and `gpa`. The attentive reader may wonder why the latter two are not listed in the attributes section of the interface, but as read-only schema fields further below. This is a trick which we used to properly display these fields on some display pages and pdf slips. However, the `attrs_to_fields` function explicitly excludes them when starting the portal, so that these fields are not used for persistent storage of same-named attributes in the database.
 
 `ICourseTicket`
 ---------------
 
+Course tickets allow students to attend a course. Lecturers can enter scores at the end of the term. A `CourseTicket` instance contains a copy of the original `Course` and `CertificateCourse` data. If the courses and/or the referring certificate courses are removed, the corresponding tickets remain unchanged. So we do not need any event triggered actions on course tickets.
+
+The `CourseTicket`  implements `waeup.kofa.students.interfaces.ICourseTicket` and also `waeup.kofa.students.interfaces.IStudentNavigation`, see above.
+
 .. literalinclude:: ../../../src/waeup/kofa/students/interfaces.py
    :pyobject: ICourseTicket
+
+The quite long list of schema fields pretends that form pages may provide these fields for editing. This is not the case. Except for `score`, all these fields are 'for display' only. They can neither be changed through the UI nor by batch processing (import). They are solely meant for backing up the orginal course data. See also :ref:`course_ticket_processor`.
+
+.. note::
+
+  It may happen that a course has been accidentally misconfigured, for example the number of credits was set too high. The course object can be corrected, but, course tickets, which refer to this course, can not. They are neither adjusted automatically nor changeable by the batch processor. The only solution to 'adjust' course tickets is to replace them by new tickets.
 
 Student Payments