source: main/waeup.kofa/trunk/src/waeup/kofa/applicants/interfaces.py @ 10832

Last change on this file since 10832 was 10831, checked in by Henrik Bettermann, 11 years ago

Implement a special application procedure. This application is meant for supplementary payments by alumni and other persons who are not students of the portal.

Attention: All custom packages have to be adjusted.

  • Property svn:keywords set to Id
File size: 17.1 KB
Line 
1## $Id: interfaces.py 10831 2013-12-10 06:24:03Z henrik $
2##
3## Copyright (C) 2011 Uli Fouquet & Henrik Bettermann
4## This program is free software; you can redistribute it and/or modify
5## it under the terms of the GNU General Public License as published by
6## the Free Software Foundation; either version 2 of the License, or
7## (at your option) any later version.
8##
9## This program is distributed in the hope that it will be useful,
10## but WITHOUT ANY WARRANTY; without even the implied warranty of
11## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12## GNU General Public License for more details.
13##
14## You should have received a copy of the GNU General Public License
15## along with this program; if not, write to the Free Software
16## Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
17##
18"""Interfaces of the university application package.
19"""
20from datetime import datetime
21from grokcore.content.interfaces import IContainer
22from zc.sourcefactory.contextual import BasicContextualSourceFactory
23from zope import schema
24from zope.component import queryUtility, getUtility
25from zope.catalog.interfaces import ICatalog
26from zope.interface import Interface, Attribute, implements, directlyProvides
27from zope.schema.interfaces import (
28    ValidationError, ISource, IContextSourceBinder)
29from waeup.kofa.browser.interfaces import IApplicantBase
30from waeup.kofa.schema import TextLineChoice, FormattedDate
31from waeup.kofa.interfaces import (
32    IKofaObject, validate_email,
33    SimpleKofaVocabulary)
34from waeup.kofa.interfaces import MessageFactory as _
35from waeup.kofa.payments.interfaces import IOnlinePayment
36from waeup.kofa.schema import PhoneNumber
37from waeup.kofa.students.vocabularies import GenderSource, RegNumberSource
38from waeup.kofa.university.vocabularies import (
39    AppCatSource, CertificateSource, SpecialApplicationSource)
40
41#: Maximum upload size for applicant passport photographs (in bytes)
42MAX_UPLOAD_SIZE = 1024 * 20
43
44_marker = object() # a marker different from None
45
46def year_range():
47    curr_year = datetime.now().year
48    return range(curr_year - 2, curr_year + 5)
49
50class RegNumInSource(ValidationError):
51    """Registration number exists already
52    """
53    # The docstring of ValidationErrors is used as error description
54    # by zope.formlib.
55    pass
56
57class ApplicantRegNumberSource(RegNumberSource):
58    """A source that accepts any reg number if not used already by a
59    different applicant.
60    """
61    cat_name = 'applicants_catalog'
62    field_name = 'reg_number'
63    validation_error = RegNumInSource
64    comp_field = 'applicant_id'
65
66def contextual_reg_num_source(context):
67    source = ApplicantRegNumberSource(context)
68    return source
69directlyProvides(contextual_reg_num_source, IContextSourceBinder)
70
71
72class AppCatCertificateSource(CertificateSource):
73    """An application certificate source delivers all certificates
74    which belong to a certain application_category.
75
76    This source is meant to be used with Applicants.
77
78    The application category must match the application category of
79    the context parent, normally an applicants container.
80    """
81    def contains(self, context, value):
82        context_appcat = getattr(getattr(
83            context, '__parent__', None), 'application_category', _marker)
84        if context_appcat is _marker:
85            # If the context (applicant) has no application category,
86            # then it might be not part of a container (yet), for
87            # instance during imports. We consider this correct.
88            return True
89        if value.application_category == context_appcat:
90            return True
91        return False
92
93    def getValues(self, context):
94        appcat = getattr(getattr(context, '__parent__', None),
95                         'application_category', None)
96        catalog = getUtility(ICatalog, name='certificates_catalog')
97        result = catalog.searchResults(
98            application_category=(appcat,appcat))
99        resultlist = getUtility(
100            IApplicantsUtils).filterCertificates(context, result)
101        return resultlist
102
103    def getTitle(self, context, value):
104        return getUtility(
105            IApplicantsUtils).getCertTitle(context, value)
106
107class ApplicationTypeSource(BasicContextualSourceFactory):
108    """An application type source delivers screening types defined in the
109    portal.
110    """
111    def getValues(self, context):
112        appcats_dict = getUtility(
113            IApplicantsUtils).APP_TYPES_DICT
114        return sorted(appcats_dict.keys())
115
116    def getToken(self, context, value):
117        return value
118
119    def getTitle(self, context, value):
120        appcats_dict = getUtility(
121            IApplicantsUtils).APP_TYPES_DICT
122        return appcats_dict[value][0]
123
124# Maybe FUTMinna still needs this ...
125#class ApplicationPinSource(BasicContextualSourceFactory):
126#    """An application pin source delivers PIN prefixes for application
127#    defined in the portal.
128#    """
129#    def getValues(self, context):
130#        apppins_dict = getUtility(
131#            IApplicantsUtils).APP_TYPES_DICT
132#        return sorted(appcats_dict.keys())
133#
134#    def getToken(self, context, value):
135#        return value
136#
137#    def getTitle(self, context, value):
138#        apppins_dict = getUtility(
139#            IApplicantsUtils).APP_TYPES_DICT
140#        return u"%s (%s)" % (
141#            apppins_dict[value][1],self.apppins_dict[value][0])
142
143application_modes_vocab = SimpleKofaVocabulary(
144    (_('Create Application Records'), 'create'),
145    (_('Update Application Records'), 'update'),
146    )
147
148class IApplicantsUtils(Interface):
149    """A collection of methods which are subject to customization.
150    """
151
152    APP_TYPES_DICT = Attribute('dict of application types')
153
154    def setPaymentDetails(container, payment):
155        """Set the payment data of an applicant.
156        """
157
158    def getApplicantsStatistics(container):
159        """Count applicants in containers.
160        """
161
162    def filterCertificates(context, resultset):
163        """Filter and sort certificates for AppCatCertificateSource.
164        """
165
166    def getCertTitle(context, value):
167        """Compose the titles in AppCatCertificateSource.
168        """
169
170class IApplicantsRoot(IKofaObject, IContainer):
171    """A container for university applicants containers.
172    """
173
174    description = schema.Text(
175        title = _(u'Human readable description in HTML format'),
176        required = False,
177        default = u'''This text can been seen by anonymous users.
178Here we put multi-lingual general information about the application procedure.
179>>de<<
180Dieser Text kann von anonymen Benutzern gelesen werden.
181Hier koennen mehrsprachige Informationen fuer Antragsteller hinterlegt werden.'''
182        )
183
184    description_dict = Attribute(
185        """Content as language dictionary with values in HTML format.""")
186
187class IApplicantsContainer(IKofaObject):
188    """An applicants container contains university applicants.
189
190    """
191
192    code = schema.TextLine(
193        title = _(u'Code'),
194        required = True,
195        readonly = True,
196        )
197
198    title = schema.TextLine(
199        title = _(u'Title'),
200        required = True,
201        readonly = False,
202        )
203
204    prefix = schema.Choice(
205        title = _(u'Application Target'),
206        required = True,
207        source = ApplicationTypeSource(),
208        readonly = True,
209        )
210
211    year = schema.Choice(
212        title = _(u'Year of Entrance'),
213        required = True,
214        values = year_range(),
215        readonly = True,
216        )
217
218    mode = schema.Choice(
219        title = _(u'Application Mode'),
220        vocabulary = application_modes_vocab,
221        required = True,
222        )
223
224    # Maybe FUTMinna still needs this ...
225    #ac_prefix = schema.Choice(
226    #    title = u'Activation code prefix',
227    #    required = True,
228    #    default = None,
229    #    source = ApplicationPinSource(),
230    #    )
231
232    application_category = schema.Choice(
233        title = _(u'Category for the grouping of certificates'),
234        required = True,
235        source = AppCatSource(),
236        )
237
238    description = schema.Text(
239        title = _(u'Human readable description in HTML format'),
240        required = False,
241        default = u'''This text can been seen by anonymous users.
242Here we put multi-lingual information about the study courses provided, the application procedure and deadlines.
243>>de<<
244Dieser Text kann von anonymen Benutzern gelesen werden.
245Hier koennen mehrsprachige Informationen fuer Antragsteller hinterlegt werden.'''
246        )
247
248    description_dict = Attribute(
249        """Content as language dictionary with values in HTML format.""")
250
251    startdate = schema.Datetime(
252        title = _(u'Application Start Date'),
253        required = False,
254        description = _('Example:') + u'2011-12-01 18:30:00+01:00',
255        )
256
257    enddate = schema.Datetime(
258        title = _(u'Application Closing Date'),
259        required = False,
260        description = _('Example:') + u'2011-12-31 23:59:59+01:00',
261        )
262
263    strict_deadline = schema.Bool(
264        title = _(u'Forbid additions after deadline (enddate)'),
265        required = False,
266        default = True,
267        )
268
269    application_fee = schema.Float(
270        title = _(u'Application Fee'),
271        default = 0.0,
272        required = False,
273        )
274
275    hidden= schema.Bool(
276        title = _(u'Hide container'),
277        required = False,
278        default = False,
279        )
280
281    def archive(id=None):
282        """Create on-dist archive of applicants stored in this term.
283
284        If id is `None`, all applicants are archived.
285
286        If id contains a single id string, only the respective
287        applicants are archived.
288
289        If id contains a list of id strings all of the respective
290        applicants types are saved to disk.
291        """
292
293    def clear(id=None, archive=True):
294        """Remove applicants of type given by 'id'.
295
296        Optionally archive the applicants.
297
298        If id is `None`, all applicants are archived.
299
300        If id contains a single id string, only the respective
301        applicants are archived.
302
303        If id contains a list of id strings all of the respective
304        applicant types are saved to disk.
305
306        If `archive` is ``False`` none of the archive-handling is done
307        and respective applicants are simply removed from the
308        database.
309        """
310
311    def writeLogMessage(view, comment):
312        """Adds an INFO message to the log file
313        """
314
315class IApplicantsContainerAdd(IApplicantsContainer):
316    """An applicants container contains university applicants.
317    """
318    prefix = schema.Choice(
319        title = _(u'Application Target'),
320        required = True,
321        source = ApplicationTypeSource(),
322        readonly = False,
323        )
324
325    year = schema.Choice(
326        title = _(u'Year of Entrance'),
327        required = True,
328        values = year_range(),
329        readonly = False,
330        )
331
332IApplicantsContainerAdd[
333    'prefix'].order =  IApplicantsContainer['prefix'].order
334IApplicantsContainerAdd[
335    'year'].order =  IApplicantsContainer['year'].order
336
337class IApplicantBaseData(IApplicantBase):
338    """The data for an applicant.
339
340    This is a base interface with no field
341    required. For use with processors, forms, etc., please use one of
342    the derived interfaces below, which set more fields to required
343    state, depending on use-case.
344    """
345
346    history = Attribute('Object history, a list of messages')
347    state = Attribute('The application state of an applicant')
348    display_fullname = Attribute('The fullname of an applicant')
349    application_date = Attribute('UTC datetime of submission, used for export only')
350    password = Attribute('Encrypted password of a applicant')
351    application_number = Attribute('The key under which the record is stored')
352
353    suspended = schema.Bool(
354        title = _(u'Account suspended'),
355        default = False,
356        required = False,
357        )
358
359    applicant_id = schema.TextLine(
360        title = _(u'Applicant Id'),
361        required = False,
362        readonly = False,
363        )
364    reg_number = TextLineChoice(
365        title = _(u'Registration Number'),
366        readonly = False,
367        required = True,
368        source = contextual_reg_num_source,
369        )
370    #access_code = schema.TextLine(
371    #    title = u'Activation Code',
372    #    required = False,
373    #    readonly = True,
374    #    )
375    firstname = schema.TextLine(
376        title = _(u'First Name'),
377        required = True,
378        )
379    middlename = schema.TextLine(
380        title = _(u'Middle Name'),
381        required = False,
382        )
383    lastname = schema.TextLine(
384        title = _(u'Last Name (Surname)'),
385        required = True,
386        )
387    date_of_birth = FormattedDate(
388        title = _(u'Date of Birth'),
389        required = False,
390        #date_format = u'%d/%m/%Y', # Use grok-instance-wide default
391        show_year = True,
392        )
393    sex = schema.Choice(
394        title = _(u'Sex'),
395        source = GenderSource(),
396        required = True,
397        )
398    email = schema.ASCIILine(
399        title = _(u'Email Address'),
400        required = False,
401        constraint=validate_email,
402        )
403    phone = PhoneNumber(
404        title = _(u'Phone'),
405        description = u'',
406        required = False,
407        )
408    course1 = schema.Choice(
409        title = _(u'1st Choice Course of Study'),
410        source = AppCatCertificateSource(),
411        required = True,
412        )
413    course2 = schema.Choice(
414        title = _(u'2nd Choice Course of Study'),
415        source = AppCatCertificateSource(),
416        required = False,
417        )
418    #school_grades = schema.List(
419    #    title = _(u'School Grades'),
420    #    value_type = ResultEntryField(),
421    #    required = False,
422    #    default = [],
423    #    )
424
425    notice = schema.Text(
426        title = _(u'Notice'),
427        required = False,
428        )
429    student_id = schema.TextLine(
430        title = _(u'Student Id'),
431        required = False,
432        readonly = False,
433        )
434    course_admitted = schema.Choice(
435        title = _(u'Admitted Course of Study'),
436        source = CertificateSource(),
437        required = False,
438        )
439    locked = schema.Bool(
440        title = _(u'Form locked'),
441        default = False,
442        required = False,
443        )
444
445    special_application = schema.Choice(
446        title = _(u'Special Application'),
447        source = SpecialApplicationSource(),
448        required = False,
449        )
450
451class IApplicant(IApplicantBaseData):
452    """An applicant.
453
454    This is basically the applicant base data. Here we repeat the
455    fields from base data if we have to set the `required` attribute
456    to True (which is the default).
457    """
458
459    def writeLogMessage(view, comment):
460        """Adds an INFO message to the log file
461        """
462
463    def createStudent():
464        """Create a student object from applicatnt data
465        and copy applicant object.
466        """
467
468class IApplicantEdit(IApplicant):
469    """An applicant interface for editing.
470
471    Here we can repeat the fields from base data and set the
472    `required` and `readonly` attributes to True to further restrict
473    the data access. Or we can allow only certain certificates to be
474    selected by choosing the appropriate source.
475
476    We cannot omit fields here. This has to be done in the
477    respective form page.
478    """
479
480    email = schema.ASCIILine(
481        title = _(u'Email Address'),
482        required = True,
483        constraint=validate_email,
484        )
485    course1 = schema.Choice(
486        title = _(u'1st Choice Course of Study'),
487        source = AppCatCertificateSource(),
488        required = True,
489        )
490    course2 = schema.Choice(
491        title = _(u'2nd Choice Course of Study'),
492        source = AppCatCertificateSource(),
493        required = False,
494        )
495    course_admitted = schema.Choice(
496        title = _(u'Admitted Course of Study'),
497        source = CertificateSource(),
498        required = False,
499        readonly = True,
500        )
501    notice = schema.Text(
502        title = _(u'Notice'),
503        required = False,
504        readonly = True,
505        )
506    special_application = schema.Choice(
507        title = _(u'Special Application'),
508        source = SpecialApplicationSource(),
509        required = True,
510        )
511
512IApplicantEdit['email'].order = IApplicantEdit[
513    'sex'].order
514
515class IApplicantUpdateByRegNo(IApplicant):
516    """Representation of an applicant.
517
518    Skip regular reg_number validation if reg_number is used for finding
519    the applicant object.
520    """
521    reg_number = schema.TextLine(
522        title = u'Registration Number',
523        required = False,
524        )
525
526class IApplicantRegisterUpdate(IApplicant):
527    """Representation of an applicant for first-time registration.
528
529    This interface is used when applicants use the registration page to
530    update their records.
531    """
532    reg_number = schema.TextLine(
533        title = u'Registration Number',
534        required = True,
535        )
536
537    firstname = schema.TextLine(
538        title = _(u'First Name'),
539        required = True,
540        )
541
542    email = schema.ASCIILine(
543        title = _(u'Email Address'),
544        required = True,
545        constraint=validate_email,
546        )
547
548class IApplicantOnlinePayment(IOnlinePayment):
549    """An applicant payment via payment gateways.
550
551    """
552
553    def doAfterApplicantPayment():
554        """Process applicant after payment was made.
555
556        """
557
558    def doAfterApplicantPaymentApproval():
559        """Process applicant after payment was approved.
560
561        """
562
563    def approveApplicantPayment():
564        """Approve payment and process applicant.
565
566        """
Note: See TracBrowser for help on using the repository browser.