Changeset 13124

Timestamp:

1 Jul 2015, 16:24:58 (10 years ago)

Author:

Henrik Bettermann

Message:

More docs.

Location:

main/waeup.kofa/trunk

Files:

• CHANGES.txt (modified) (1 diff)
• docs/source/userdocs/browsing.rst (modified) (1 diff)
• docs/source/userdocs/customization.rst (modified) (2 diffs)
• src/waeup/kofa/students/utils.py (modified) (13 diffs)
• src/waeup/kofa/utils/utils.py (modified) (6 diffs)

main/waeup.kofa/trunk/CHANGES.txt

@@ -5 +5 @@
 =======================
 
-* Do not create special application payment tickets with Zero amount.
+* Do not create special application payment tickets with zero amount.
 
 * Remove manual clearance lock. Replace `clearance_locked` field by

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

@@ -57 +57 @@
 
 
-.. _manage_edit_pages:
+.. _views_pages:
 
 Views, Pages and Form Pages

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

@@ -49 +49 @@
 localization. Translation is done via ``po`` text files which are
 located in the ``locales`` folder of a package. Each language has
-its own subfolder. Localized English Kofa terms, for intance, can be
+its own subfolder. Localized English Kofa terms, for instance, can be
 found in ``locales/en/LC_MESSAGES/waeup.kofa.po``. A single
 entry/message consists of two lines.
@@ -71 +71 @@
 ===============
 
+Adding further schema field attributes to content components can be
+done by inheriting Zope interfaces from the base package and adding
+new schema fields to these custom interfaces, see :ref:`note
+<kofa_interfaces>`. This sounds simple, but it isn't. There are many
+things to think about, when customizing interfaces:
+
+1. A customized interface alone doesn't have any effect, beause the
+   content classes still implement the original interfaces. Thus, also
+   all content classes, which are supposed to implement the extended
+   interfaces, must be customized, and must be registered instead of
+   the orginal classes which they inherit from. Drawback is, that this
+   must be done before the first start-up of the portal. Otherwise,
+   instances of the original content classes might have been created
+   which cannot be changed afterwards.
+
+2. Also the forms which are being auto-generated by
+   `grok.AutoFields` (see :ref:`views_pages`), must be customized and
+   use the new and extended interfaces. Otherwise added fields won't
+   appear on form pages.
+
+3. The same holds for exporters and importers. They also consider
+   the fields from interfaces when processing the data. If we forget to
+   customize exporter or batch processor classes, only the fields from
+   the original interfaces will be exported or reimported.
+
+
 Zope Utilities
 ==============
 
-Zope utilities are dedicated to customization by overriding their methods in custom packages.
+Kofa's global utilities are perfectly suited for customization.
+Their attributes and methods can be easily overridden in custom
+packages.
 
 Kofa Utils
 ----------
 
+The central `KofaUtils` utility contains not only most dictionaries
+used for sources (see
+:py:class:`API <waeup.kofa.utils.utils.KofaUtils>`) but also attributes 
+like `PORTAL_LANGUAGE` and `tzinfo`. The first defines the default
+language, which is used for pdf slips. The second defines the time
+zone where the institution is located.
+
+Customizable utility methods are:
+
+.. automethod:: waeup.kofa.utils.utils.KofaUtils.sendContactForm()
+   :noindex:
+
+.. automethod:: waeup.kofa.utils.utils.KofaUtils.fullname()
+   :noindex:
+
+.. automethod:: waeup.kofa.utils.utils.KofaUtils.genPassword()
+   :noindex:
+
+.. automethod:: waeup.kofa.utils.utils.KofaUtils.sendCredentials()
+   :noindex:
+
+.. automethod:: waeup.kofa.utils.utils.KofaUtils.getPaymentItem()
+   :noindex:
+
 Students Utils
 --------------
+
+Customizable utility methods are:
+
+.. automethod:: waeup.kofa.students.utils.StudentsUtils.getReturningData()
+   :noindex:
+
+.. automethod:: waeup.kofa.students.utils.StudentsUtils.setReturningData()
+   :noindex:
+
+.. automethod:: waeup.kofa.students.utils.StudentsUtils.setPaymentDetails()
+   :noindex:
+
+.. automethod:: waeup.kofa.students.utils.StudentsUtils.setBalanceDetails()
+   :noindex:
+
+.. automethod:: waeup.kofa.students.utils.StudentsUtils.increaseMatricInteger()
+   :noindex:
+
+.. automethod:: waeup.kofa.students.utils.StudentsUtils.constructMatricNumber()
+   :noindex:
+
+.. automethod:: waeup.kofa.students.utils.StudentsUtils.setMatricNumber()
+   :noindex:
+
+.. automethod:: waeup.kofa.students.utils.StudentsUtils.getAccommodationDetails()
+   :noindex:
+
+.. automethod:: waeup.kofa.students.utils.StudentsUtils.selectBed()
+   :noindex:
+
+.. automethod:: waeup.kofa.students.utils.StudentsUtils.renderPDFAdmissionLetter()
+   :noindex:
+
+.. automethod:: waeup.kofa.students.utils.StudentsUtils.getPDFCreator()
+   :noindex:
+
+.. automethod:: waeup.kofa.students.utils.StudentsUtils.renderPDF()
+   :noindex:
+
+.. automethod:: waeup.kofa.students.utils.StudentsUtils.renderPDFTranscript()
+   :noindex:
+
+.. automethod:: waeup.kofa.students.utils.StudentsUtils.maxCredits()
+   :noindex:
+
+.. automethod:: waeup.kofa.students.utils.StudentsUtils.getBedCoordinates()
+   :noindex:
+
+
+
 
 Applicants Utils

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

@@ -323 +323 @@
         """ Define what happens after school fee payment
         depending on the student's senate verdict.
-
         In the base configuration current level is always increased
         by 100 no matter which verdict has been assigned.
@@ -334 +333 @@
         """ Define what happens after school fee payment
         depending on the student's senate verdict.
-
-        This method folllows the same algorithm as getReturningData but
+        This method folllows the same algorithm as `getReturningData` but
         it also sets the new values.
         """
@@ -376 +374 @@
     def setPaymentDetails(self, category, student,
             previous_session, previous_level):
-        """Create a payment ticket object and set the payment data of a
+        """Create a payment ticket and set the payment data of a
         student for the payment category specified.
         """
@@ -491 +489 @@
     def setBalanceDetails(self, category, student,
             balance_session, balance_level, balance_amount):
-        """Create Payment object and set the payment data of a student for.
-
+        """Create a balance payment ticket and set the payment data
+        as selected by the student.
         """
         p_item = u'Balance'
@@ -519 +517 @@
     def increaseMatricInteger(self, student):
         """Increase counter for matric numbers.
-
         This counter can be a centrally stored attribute or an attribute of 
         faculties, departments or certificates. In the base package the counter
-        is as an attribute of the site configuration object.
+        is as an attribute of the site configuration container.
         """
         grok.getSite()['configuration'].next_matric_integer += 1
@@ -530 +527 @@
         """Fetch the matric number counter which fits the student and
         construct the new matric number of the student.
-
         In the base package the counter is returned which is as an attribute
-        of the site configuration object.
+        of the site configuration container.
         """
         next_integer = grok.getSite()['configuration'].next_matric_integer
@@ -540 +536 @@
 
     def setMatricNumber(self, student):
-        """Set matriculation number of student.
-
-        If the student's matric number is unset a new matric number is
+        """Set matriculation number of student. If the student's matric number
+        is unset a new matric number is
         constructed according to the matriculation number construction rules
-        defined in the constructMatricNumber method. The new matric number is 
+        defined in the `constructMatricNumber` method. The new matric number is
         set, the students catalog updated. The corresponding matric number
         counter is increased by one.
@@ -550 +545 @@
         This method is tested but not used in the base package. It can
         be used in custom packages by adding respective views
-        and by customizing increaseMatricInteger and constructMatricNumber
+        and by customizing `increaseMatricInteger` and `constructMatricNumber`
         according to the university's matriculation number construction rules.
 
@@ -607 +602 @@
     def selectBed(self, available_beds):
         """Select a bed from a list of available beds.
-
         In the base configuration we select the first bed found,
         but can also randomize the selection if we like.
@@ -680 +674 @@
     def getPDFCreator(self, context):
         """Get a pdf creator suitable for `context`.
-
         The default implementation always returns the default creator.
         """
@@ -800 +793 @@
                   omit_fields=(),
                   tableheader=None):
-        """Render pdf slips for transcript.
+        """Render pdf slips for transcripts.
         """
         portal_language = getUtility(IKofaUtils).PORTAL_LANGUAGE
@@ -905 +898 @@
     def maxCredits(self, studylevel):
         """Return maximum credits.
-
-        In some universities maximum credits is not constant, it
-        depends on the student's study level. Set maxCredits None or 0
+        At some universities maximum credits is not constant, it
+        depends on the student's study level. Set `maxCredits` None or 0
         in order to deactivate the limitation.
         """
@@ -921 +913 @@
     def getBedCoordinates(self, bedticket):
         """Return bed coordinates.
-
-        This method can be used to customize the display_coordinates
+        This method can be used to customize the `display_coordinates`
         property method.
         """

main/waeup.kofa/trunk/src/waeup/kofa/utils/utils.py

@@ -80 +80 @@
 class KofaUtils(grok.GlobalUtility):
     """A collection of parameters and methods subject to customization.
-
     """
     grok.implements(IKofaUtils)
@@ -242 +241 @@
     @property
     def tzinfo(self):
+        """Time zone of the university.
+        """
         # For Nigeria: pytz.timezone('Africa/Lagos')
         # For Germany: pytz.timezone('Europe/Berlin')
@@ -247 +248 @@
 
     def fullname(self, firstname, lastname, middlename=None):
-        """Full name constructor.
+        """Construct fullname.
         """
         # We do not necessarily have the middlename attribute
@@ -263 +264 @@
 
     def sendCredentials(self, user, password=None, url_info=None, msg=None):
-        """Send credentials as email.
-
-        Input is the applicant for which credentials are sent and the
-        password.
-
-        Returns True or False to indicate successful operation.
+        """Send credentials as email. Input is the user for which credentials
+        are sent and the password. Method returns True or False to indicate
+        successful operation.
         """
         subject = 'Your Kofa credentials'
@@ -308 +306 @@
 
     def getPaymentItem(self, payment):
-        """Return payment item.
-
-        This method can be used to customize the display_item property method.
+        """Return payment item. This method can be used to customize the
+        `display_item` property attribute, e.g. in order to hide bed coordinates
+        if maintenance fee is not paid.
         """
         return payment.p_item
@@ -316 +314 @@
     def expensive_actions_allowed(self, type=None, request=None):
         """Tell, whether expensive actions are currently allowed.
-
         Check system load/health (or other external circumstances) and
         locally set values to see, whether expensive actions should be
         allowed (`True`) or better avoided (`False`).
-
         Use this to allow or forbid exports, report generations, or
         similar actions.