Changeset 12999


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

More docs.

Location:
main/waeup.kofa/trunk
Files:
2 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
  • main/waeup.kofa/trunk/src/waeup/kofa/students/interfaces.py

    r12997 r12999  
    122122    def getAccommodation_details(student):
    123123        """Determine the accommodation dates of a student.
    124 
    125124        """
    126125
    127126    def selectBed(available_beds):
    128127        """Select a bed from a list of available beds.
    129 
    130128        In the standard configuration we select the first bed found,
    131129        but can also randomize the selection if we like.
     
    138136    def renderPDF(view, subject='', filename='slip.pdf',):
    139137        """Render pdf slips for various pages.
    140 
    141138        """
    142139
     
    194191    """
    195192    password = Attribute('Encrypted password')
    196     temp_password = Attribute(
    197         'Dictionary with user name, timestamp and encrypted password')
     193    temp_password = Attribute('Dictionary with user name, timestamp and encrypted password')
    198194    history = Attribute('Object history, a list of messages')
    199195    state = Attribute('Registration state')
     
    287283
    288284    def writeLogMessage(view, message):
    289         """Write formatted log message into student.log.
     285        """Write formatted log message into students.log.
    290286        """
    291287
     
    344340class IPGStudentClearance(IUGStudentClearance):
    345341    """Representation of postgraduate student clearance data.
    346 
    347342    """
    348343    employer = schema.TextLine(
     
    354349class IStudentPersonal(IKofaObject):
    355350    """Representation of student personal data.
    356 
    357351    """
    358352    personal_updated = schema.Datetime(
     
    369363class IStudentTranscript(IKofaObject):
    370364    """Representation of student transcript data.
    371 
    372365    """
    373366
     
    381374    IStudentPersonal, IStudentTranscript):
    382375    """Representation of a student.
    383 
    384376    """
    385377
     
    405397class IStudentUpdateByMatricNo(IStudent):
    406398    """Representation of a student. Skip regular matric_number validation.
    407 
    408399    """
    409400    matric_number = schema.TextLine(
     
    413404
    414405class IStudentRequestPW(IStudent):
    415     """Representation of an student for first-time password request.
    416 
     406    """Representation of a student for first-time password request.
    417407    This interface is used when students use the requestpw page to
    418408    login for the the first time.
     
    435425
    436426class IStudentStudyCourse(IKofaObject):
    437     """A container for student study levels.
    438 
     427    """Representation of student study course data.
    439428    """
    440429    certificate = schema.Choice(
     
    488477
    489478class IStudentStudyCourseTransfer(IStudentStudyCourse):
    490     """An student transfers.
    491 
    492     """
    493 
     479    """An interface used for student transfers.
     480    """
    494481    certificate = schema.Choice(
    495482        title = _(u'Certificate'),
     
    521508class IStudentStudyCourseTranscript(IKofaObject):
    522509    """An interface for student transcripts.
    523 
    524     """
    525 
     510    """
    526511    entry_mode = schema.Choice(
    527512        title = _(u'Entry Mode'),
     
    541526class IStudentVerdictUpdate(IKofaObject):
    542527    """A interface for verdict imports.
    543 
    544     """
    545 
     528    """
    546529    current_verdict = schema.Choice(
    547530        title = _(u'Current Verdict'),
     
    573556
    574557class IStudentStudyLevel(IKofaObject):
    575     """A container for course tickets.
    576 
     558    """A representation of student study level data.
    577559    """
    578560    number_of_tickets = Attribute('Number of tickets contained in this level')
     
    635617
    636618class ICourseTicket(IKofaObject):
    637     """An interface for course tickets.
    638 
     619    """A representation of course ticket data.
    639620    """
    640621    code = Attribute('code of the original course')
     
    705686class ICourseTicketAdd(IKofaObject):
    706687    """An interface for adding course tickets.
    707 
    708688    """
    709689    course = schema.Choice(
     
    715695class ICourseTicketImport(ICourseTicket):
    716696    """An interface for importing course results and nothing more.
    717 
    718697    """
    719698    score = schema.Int(
     
    732711class IStudentAccommodation(IKofaObject):
    733712    """A container for student accommodation objects.
    734 
    735713    """
    736714
     
    741719
    742720class IBedTicket(IKofaObject):
    743     """A ticket for accommodation booking.
    744 
     721    """A representation of accommodation booking data.
    745722    """
    746723    bed = Attribute('The bed object.')
     
    785762    def getSessionString():
    786763        """Returns the title of academic_sessions_vocab term.
    787 
    788764        """
    789765
    790766class IStudentPaymentsContainer(IPaymentsContainer):
    791767    """A container for student payment objects.
    792 
    793768    """
    794769
    795770class IStudentOnlinePayment(IOnlinePayment):
    796771    """A student payment via payment gateways.
    797 
    798772    """
    799773
     
    811785    def doAfterStudentPayment():
    812786        """Process student after payment was made.
    813 
    814787        """
    815788
    816789    def doAfterStudentPaymentApproval():
    817790        """Process student after payment was approved.
    818 
    819791        """
    820792
    821793    def approveStudentPayment():
    822794        """Approve payment and process student.
    823 
    824795        """
    825796
     
    829800class IStudentPreviousPayment(IKofaObject):
    830801    """An interface for adding previous session payments.
    831 
    832802    """
    833803
     
    853823class IStudentBalancePayment(IKofaObject):
    854824    """An interface for adding balances.
    855 
    856825    """
    857826
Note: See TracChangeset for help on using the changeset viewer.