source: main/waeup.kofa/trunk/docs/source/userdocs/customization.rst @ 17356

Last change on this file since 17356 was 14655, checked in by Henrik Bettermann, 8 years ago

Update IStudentsUtils and docs.

File size: 8.4 KB
Line 
1.. _customization:
2
3Portal Customization
4********************
5
6Portal customization requires profound knowledge of the Python
7programming language. Customization is part of the portal deployment
8process. It can only be done by the custom package manager and
9activated by the system administrator, who is allowed to
10update/upgrade the package on the server and restart the portal.
11Usually, custom packages are not designed for regular
12reconfiguration. Due to the complexity of school fee computation at
13Nigerian universities, however, a lot of configuration had to be
14done in the Python code and can thus not be subject to online
15configuration. Technically speaking, the parameters are only loaded
16and registered once during start-up and are not stored in the
17database like the configuration parameters described in
18:ref:`configuration`.
19
20Kofa must not be customized by manipulating original Kofa code, i.e.
21by editing Python files, Zope page templates or ZCML configuration
22files in the Kofa base package. Customization is done by deploying a
23custom package which can inherit all the Python classes from the
24base package, in order to override distinct attributes and methods
25and register these customized classes instead of the orginal classes
26during start-up. It would go beyond the scope of the user handbook
27to explain, how to build such a Kofa custom package. This will be
28done in the :ref:`developer_handbook`. Here we roughly describe the
29three different customization approaches with a focus on the third
30approach, the customization of utility attributes and methods.
31
32Localization
33============
34
35The base language of the Kofa User Interface (Kofa UI) is English.
36The English language regime has been specified by WAeUP's first
37customer, the University of Benin in Nigeria. Kofa is language-aware,
38which means it has been translated into different languages (German
39and French so far), and the preferred language can be selected via
40the UI. The Kofa UI translations and also the English language
41regime can be localized in custom packages by overriding single
42entries of the language files. Headlines, field labels, field
43descriptions, navigation tabs, buttons, page comments, flash
44messages etc. can be easily adjusted to the needs of the institution
45which wants to deploy Kofa.
46
47Kofa is using the `GNU gettext utilities
48<http://www.gnu.org/software/gettext>`_ for translation and
49localization. Translation is done via ``po`` text files which are
50located in the ``locales`` folder of a package. Each language has
51its own subfolder. Localized English Kofa terms, for instance, can be
52found in ``locales/en/LC_MESSAGES/waeup.kofa.po``. A single
53entry/message consists of two lines.
54
55Example::
56
57  msgid "Login"
58  msgstr "Let me in"
59
60``msgid`` contains the original term from the base package,
61``msgstr`` contains its localized/translated version, which results
62into a renamed login tab on the right side of the navigation bar.
63
64``po`` files must be compiled before restarting the portal. Editing
65and compilation of ``po`` files can be done with a nice tool called
66'Poedit' which is `available <https://poedit.net/download>`_ for
67various operating systems.
68
69
70Zope Interfaces
71===============
72
73Adding further schema field attributes to content components can be
74done by inheriting Zope interfaces from the base package and adding
75new schema fields to these custom interfaces, see :ref:`note
76<kofa_interfaces>`. This sounds simple, but it isn't. There are many
77things to think about, when customizing interfaces:
78
791. A customized interface alone doesn't have any effect, beause the
80   content classes still implement the original interfaces. Thus, also
81   all content classes, which are supposed to implement the extended
82   interfaces, must be customized, and must be registered instead of
83   the orginal classes which they inherit from. Drawback is, that this
84   must be done before the first start-up of the portal. Otherwise,
85   instances of the original content classes might have been created
86   which cannot be changed afterwards.
87
882. Also the forms which are being auto-generated by
89   `grok.AutoFields` (see :ref:`views_pages`), must be customized and
90   use the new and extended interfaces. Otherwise added fields won't
91   appear on form pages.
92
933. The same holds for exporters and importers. They also consider
94   the fields from interfaces when processing the data. If we forget to
95   customize exporter or batch processor classes, only the fields from
96   the original interfaces will be exported or reimported.
97
98
99Zope Utilities
100==============
101
102Kofa's global utilities are perfectly suited for customization.
103Their attributes and methods can be easily overridden in custom
104packages.
105
106Kofa Utils
107----------
108
109The central `KofaUtils` utility contains not only most dictionaries
110used for sources (see :py:class:`API
111<waeup.kofa.utils.utils.KofaUtils>`) but also **configuration
112attributes** like:
113
114.. autoattribute:: waeup.kofa.utils.utils.KofaUtils.PORTAL_LANGUAGE
115   :noindex:
116
117.. autoattribute:: waeup.kofa.utils.utils.KofaUtils.tzinfo
118   :noindex:
119
120.. autoattribute:: waeup.kofa.utils.utils.KofaUtils.SYSTEM_MAX_LOAD
121   :noindex:
122
123Customizable **utility methods** are:
124
125.. automethod:: waeup.kofa.utils.utils.KofaUtils.sendContactForm
126   :noindex:
127
128.. automethod:: waeup.kofa.utils.utils.KofaUtils.fullname
129   :noindex:
130
131.. automethod:: waeup.kofa.utils.utils.KofaUtils.genPassword
132   :noindex:
133
134.. automethod:: waeup.kofa.utils.utils.KofaUtils.sendCredentials
135   :noindex:
136
137.. automethod:: waeup.kofa.utils.utils.KofaUtils.getPaymentItem
138   :noindex:
139
140Students Utilities
141------------------
142
143`StudentsUtils` contains the following **configuration attributes**:
144
145.. autoattribute:: waeup.kofa.students.utils.StudentsUtils.STUDENT_ID_PREFIX
146   :noindex:
147
148.. autoattribute:: waeup.kofa.students.utils.StudentsUtils.SKIP_UPLOAD_VIEWLETS
149   :noindex:
150
151.. autoattribute:: waeup.kofa.students.utils.StudentsUtils.PORTRAIT_CHANGE_STATES
152   :noindex:
153
154.. autoattribute:: waeup.kofa.students.utils.StudentsUtils.SEPARATORS_DICT
155   :noindex:
156
157.. autoattribute:: waeup.kofa.students.utils.StudentsUtils.STUDENT_EXPORTER_NAMES
158   :noindex:
159
160.. autoattribute:: waeup.kofa.students.utils.StudentsUtils.STUDENT_BACKUP_EXPORTER_NAMES
161   :noindex:
162
163Customizable **utility methods** are:
164
165.. automethod:: waeup.kofa.students.utils.StudentsUtils.getReturningData
166   :noindex:
167
168.. automethod:: waeup.kofa.students.utils.StudentsUtils.setReturningData
169   :noindex:
170
171.. automethod:: waeup.kofa.students.utils.StudentsUtils.setPaymentDetails
172   :noindex:
173
174.. automethod:: waeup.kofa.students.utils.StudentsUtils.setBalanceDetails
175   :noindex:
176
177.. automethod:: waeup.kofa.students.utils.StudentsUtils.increaseMatricInteger
178   :noindex:
179
180.. automethod:: waeup.kofa.students.utils.StudentsUtils.constructMatricNumber
181   :noindex:
182
183.. automethod:: waeup.kofa.students.utils.StudentsUtils.setMatricNumber
184   :noindex:
185
186.. automethod:: waeup.kofa.students.utils.StudentsUtils.getAccommodationDetails
187   :noindex:
188
189.. automethod:: waeup.kofa.students.utils.StudentsUtils.selectBed
190   :noindex:
191
192.. automethod:: waeup.kofa.students.utils.StudentsUtils.getPDFCreator
193   :noindex:
194
195.. automethod:: waeup.kofa.students.utils.StudentsUtils.renderPDF
196   :noindex:
197
198.. automethod:: waeup.kofa.students.utils.StudentsUtils.renderPDFAdmissionLetter
199   :noindex:
200
201.. automethod:: waeup.kofa.students.utils.StudentsUtils.renderPDFCourseticketsOverview
202   :noindex:
203
204.. automethod:: waeup.kofa.students.utils.StudentsUtils.renderPDFTranscript
205   :noindex:
206
207.. automethod:: waeup.kofa.students.utils.StudentsUtils.getDegreeClassNumber
208   :noindex:
209
210.. automethod:: waeup.kofa.students.utils.StudentsUtils.warnCreditsOOR
211   :noindex:
212
213.. automethod:: waeup.kofa.students.utils.StudentsUtils.getBedCoordinates
214   :noindex:
215
216.. automethod:: waeup.kofa.students.utils.StudentsUtils.clearance_disabled_message
217   :noindex:
218
219
220Applicants Utililties
221---------------------
222
223`ApplicantsUtils` contains the following **configuration attributes**:
224
225.. autoattribute:: waeup.kofa.applicants.utils.ApplicantsUtils.APP_TYPES_DICT
226   :noindex:
227
228.. autoattribute:: waeup.kofa.applicants.utils.ApplicantsUtils.SEPARATORS_DICT
229   :noindex:
230
231Customizable **utility methods** are:
232
233.. automethod:: waeup.kofa.applicants.utils.ApplicantsUtils.setPaymentDetails
234   :noindex:
235
236.. automethod:: waeup.kofa.applicants.utils.ApplicantsUtils.getApplicantsStatistics
237   :noindex:
238
239.. automethod:: waeup.kofa.applicants.utils.ApplicantsUtils.sortCertificates
240   :noindex:
241
242.. automethod:: waeup.kofa.applicants.utils.ApplicantsUtils.getCertTitle
243   :noindex:
Note: See TracBrowser for help on using the repository browser.