Changeset 12999 for main/waeup.kofa/trunk/docs

Timestamp:

25 May 2015, 20:50:37 (9 years ago)

Author:

Henrik Bettermann

Message:

More docs.

File:

• main/waeup.kofa/trunk/docs/source/userdocs/students.rst (modified) (3 diffs)

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

@@ -37 +37 @@
 ========
 
-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: ``studycourse``  (instance of `StudentStudyCourse`), ``payments`` (instance of `StudentPaymentsContainer`)  ``accommodation`` (instance of `StudentAccommodation`). The purposes of them are described further below.
+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: ``studycourse``  (instance of `StudentStudyCourse`), ``payments`` (instance of `StudentPaymentsContainer`)  and ``accommodation`` (instance of `StudentAccommodation`). The purposes of them are described further below.
 
 Let's talk about the attributes and methods belonging to the `Student` class, the so-called 'external behaviour' of student objects specified in Zope 'interfaces'. The data stored with each student object are subdivided into three parts: base data, personal data and clearance data. Each part has its own interface.
@@ -45 +45 @@
 .. note::
 
-  **Interfaces** are one of the pillars of Zope's Component Architecture (ZCA, see also :ref:`prerequisites`). They document the 'external behaviour' of objects. In Kofa interfaces are used to specify the attributes, methods and schema fields of objects. The first two are well-known Python concepts. A Zope schema field is a bit more complicated. It's a detailed description of a field to be submitted via forms to the server, or which is processed by a batch processor. In both cases the input data are being validated against the schema field. In Kofa, schema fields in interfaces are also used to automtically add `FieldProperty` attributes of the same name to most content classes. This is done by a class function called :py:func:`attrs_to_fields<waeup.kofa.utils.helpers.attrs_to_fields>` during startup. These class attributes ensure that corresponding attributes of instances of this class - when being added or changed - always meet the requirements of the schema field. Another big advantage of such class attributes is, that attributes with a `FieldProperty` do not need to be set in `__init__` methods.
+  **Interfaces** are one of the pillars of Zope's Component Architecture (ZCA, see also :ref:`prerequisites`). They document the 'external behaviour' of objects. In Kofa interfaces are used to specify the attributes, methods and schema fields of objects. The first two are well-known Python concepts. A Zope schema field is a bit more complicated. It's a detailed description of a field to be submitted via forms to the server, or which is processed by a batch processor. In both cases the input data are being validated against the schema field requirements. In Kofa, schema fields (see also note below) in interfaces are also used to automtically add `FieldProperty` attributes of the same name to most content classes. This is done by a function :py:func:`attrs_to_fields<waeup.kofa.utils.helpers.attrs_to_fields>` which is called once during startup of Kofa. These class attributes ensure that corresponding attributes of instances of this class - when being added or changed - always meet the requirements of the schema field. Another big advantage of such class attributes is, that attributes with a `FieldProperty` do not need to be set in `__init__` methods.
 
-All student classes implement `waeup.kofa.students.interfaces.IStudent` which defines a base set of attributes, schema fields and methods all students must provide. This 'behaviour' is fundamental so that we quote and explain the source code here.
+The `Student` class implements several interfaces which we will quote to unveil the student's 'external behaviour'.
+
+`IStudentBase`
+--------------
+
+`waeup.kofa.students.interfaces.IStudentBase` defines a fundamental set of attributes, schema fields and methods which are being used throughout the portal. This set is immutable. No class statement must be removed or added in customized versions of Kofa.
 
 .. literalinclude:: ../../../src/waeup/kofa/students/interfaces.py
@@ -70 +75 @@
 The **third part** of the interface lists the methods which can be applied to student objects.
 
+`IUGStudentClearance`
+---------------------
+
+Much like all the following student interfaces, `waeup.kofa.students.interfaces.IUGStudentClearance` describes an additional set of schema fields which are exclusively used on form pages. They do not play any role beyond that purpose. Any kind of schema field can be safely added in customized versions of these interfaces to meet the conditions of the university's matriculation process. Also `date_of_birth` and `nationality` are not used in the base package for further data processing which means, there is no dependency on these two parameters. Attention: This might be different in customized versions of Kofa. Some views might use these parameters to restrict access or make actions (e.g. payment of items) conditional on the student's nationality or current age.
+
+.. literalinclude:: ../../../src/waeup/kofa/students/interfaces.py
+   :pyobject: IUGStudentClearance
+
+`clearance_locked` controls the access to the edit form page of clearance data. The corresponding attribute is automatically set by workflow transitions to lock or unlock the edit form page respectively. The attribute can also be set by officers via the manage form page to lock or unlock the page manually.
+
+`officer_comment` is usually edited by clearance officers when rejecting clearance previously requested by the student. The attribute contains the message which informs the student about the reasons of rejection. The attribute is cleared after final clearance. The message can be also found in ``students.log``.
+
+Both `clearance_locked` and `officer_comment` are controlled by workflow transitions not by states, see below.
+
+`IPGStudentClearance`
+---------------------
+
+Most universities acquire different data from undergraduate (UG) and postgraduate (PG) students. The forms vary widely. Therefore Kofa offers a second interface for acquiring PG clearance data. In the base package `IPGStudentClearance` inherits from the `IUGStudentClearance` interface. The additional `employer` field in the base package only serves as an example.
+
+.. literalinclude:: ../../../src/waeup/kofa/students/interfaces.py
+   :pyobject: IPGStudentClearance
+
+`IStudentPersonal`
+------------------
+
+`waeup.kofa.students.interfaces.IUGStudentPersonal` defines an additional set of personal student data which are permantly editable by students. The set usually contains further contact data and information about the student's relatives.
+
+.. literalinclude:: ../../../src/waeup/kofa/students/interfaces.py
+   :pyobject: IStudentPersonal
+
+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.
 
 Student Study Courses
 =====================
 
+All data related to the student's course of study are stored with the ``studycourse`` object which is an instance of the `StudentStudyCourse` class. The latter implements `waeup.kofa.students.interfaces.IStudentStudyCourse`.
+
+`IStudentStudyCourse`
+---------------------
+
+.. literalinclude:: ../../../src/waeup/kofa/students/interfaces.py
+   :pyobject: IStudentStudyCourse
+
 Student Study Levels
+====================
+
+`IStudentStudyLevel`
 --------------------
+
+.. literalinclude:: ../../../src/waeup/kofa/students/interfaces.py
+   :pyobject: IStudentStudyLevel
+
+`ICourseTicket`
+---------------
+
+.. literalinclude:: ../../../src/waeup/kofa/students/interfaces.py
+   :pyobject: ICourseTicket
 
 Student Payments
 ================
 
+`IStudentOnlinePayment`
+-----------------------
+
+.. literalinclude:: ../../../src/waeup/kofa/students/interfaces.py
+   :pyobject: IStudentOnlinePayment
+
 Student Accommodation
 =====================
 
+`IBedTicket`
+------------
+
+.. literalinclude:: ../../../src/waeup/kofa/students/interfaces.py
+   :pyobject: IBedTicket
+
+
+Registration Workflow
+=====================
+
+Browser Pages
+=============
+
 
 .. _zope schema: http://docs.zope.org/zope.schema