Ignore:
Timestamp:
25 May 2015, 20:50:37 (10 years ago)
Author:
Henrik Bettermann
Message:

More docs.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • main/waeup.kofa/trunk/docs/source/userdocs/students.rst

    r12998 r12999  
    3737========
    3838
    39 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.
     39The `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.
    4040
    4141Let'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.
     
    4545.. note::
    4646
    47   **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.
     47  **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.
    4848
    49 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.
     49The `Student` class implements several interfaces which we will quote to unveil the student's 'external behaviour'.
     50
     51`IStudentBase`
     52--------------
     53
     54`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.
    5055
    5156.. literalinclude:: ../../../src/waeup/kofa/students/interfaces.py
     
    7075The **third part** of the interface lists the methods which can be applied to student objects.
    7176
     77`IUGStudentClearance`
     78---------------------
     79
     80Much 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.
     81
     82.. literalinclude:: ../../../src/waeup/kofa/students/interfaces.py
     83   :pyobject: IUGStudentClearance
     84
     85`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.
     86
     87`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``.
     88
     89Both `clearance_locked` and `officer_comment` are controlled by workflow transitions not by states, see below.
     90
     91`IPGStudentClearance`
     92---------------------
     93
     94Most 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.
     95
     96.. literalinclude:: ../../../src/waeup/kofa/students/interfaces.py
     97   :pyobject: IPGStudentClearance
     98
     99`IStudentPersonal`
     100------------------
     101
     102`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.
     103
     104.. literalinclude:: ../../../src/waeup/kofa/students/interfaces.py
     105   :pyobject: IStudentPersonal
     106
     107Kofa 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.
    72108
    73109Student Study Courses
    74110=====================
    75111
     112All 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`.
     113
     114`IStudentStudyCourse`
     115---------------------
     116
     117.. literalinclude:: ../../../src/waeup/kofa/students/interfaces.py
     118   :pyobject: IStudentStudyCourse
     119
    76120Student Study Levels
     121====================
     122
     123`IStudentStudyLevel`
    77124--------------------
     125
     126.. literalinclude:: ../../../src/waeup/kofa/students/interfaces.py
     127   :pyobject: IStudentStudyLevel
     128
     129`ICourseTicket`
     130---------------
     131
     132.. literalinclude:: ../../../src/waeup/kofa/students/interfaces.py
     133   :pyobject: ICourseTicket
    78134
    79135Student Payments
    80136================
    81137
     138`IStudentOnlinePayment`
     139-----------------------
     140
     141.. literalinclude:: ../../../src/waeup/kofa/students/interfaces.py
     142   :pyobject: IStudentOnlinePayment
     143
    82144Student Accommodation
    83145=====================
    84146
     147`IBedTicket`
     148------------
     149
     150.. literalinclude:: ../../../src/waeup/kofa/students/interfaces.py
     151   :pyobject: IBedTicket
     152
     153
     154Registration Workflow
     155=====================
     156
     157Browser Pages
     158=============
     159
    85160
    86161.. _zope schema: http://docs.zope.org/zope.schema
Note: See TracChangeset for help on using the changeset viewer.