source: main/waeup.kofa/branches/0.2/src/waeup/kofa/applicants/interfaces.py @ 17808

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

Add description.

  • Property svn:keywords set to Id
File size: 19.2 KB
Line 
1## $Id: interfaces.py 10846 2013-12-15 07:12:17Z 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 ISpecialApplicant(IApplicantBase):
469    """A special applicant.
470
471    This reduced interface is for former students or students who are not
472    users of the portal but have to pay supplementary fees.
473
474    This interface is used in browser components only. Thus we can't add
475    fields here to the regular IApplicant interface here. We can
476    only 'customize' fields.
477    """
478
479    history = Attribute('Object history, a list of messages')
480    state = Attribute('The application state of an applicant')
481    display_fullname = Attribute('The fullname of an applicant')
482    application_date = Attribute('UTC datetime of submission, used for export only')
483    password = Attribute('Encrypted password of a applicant')
484    application_number = Attribute('The key under which the record is stored')
485
486    suspended = schema.Bool(
487        title = _(u'Account suspended'),
488        default = False,
489        required = False,
490        )
491
492    applicant_id = schema.TextLine(
493        title = _(u'Applicant Id'),
494        required = False,
495        readonly = False,
496        )
497
498    firstname = schema.TextLine(
499        title = _(u'First Name'),
500        required = True,
501        )
502
503    middlename = schema.TextLine(
504        title = _(u'Middle Name'),
505        required = False,
506        )
507
508    lastname = schema.TextLine(
509        title = _(u'Last Name (Surname)'),
510        required = True,
511        )
512
513    reg_number = TextLineChoice(
514        title = _(u'Identification Number'),
515        description = u'Enter either registration or matriculation number.',
516        readonly = False,
517        required = True,
518        source = contextual_reg_num_source,
519        )
520
521    date_of_birth = FormattedDate(
522        title = _(u'Date of Birth'),
523        required = False,
524        #date_format = u'%d/%m/%Y', # Use grok-instance-wide default
525        show_year = True,
526        )
527
528    email = schema.ASCIILine(
529        title = _(u'Email Address'),
530        required = True,
531        constraint=validate_email,
532        )
533
534    phone = PhoneNumber(
535        title = _(u'Phone'),
536        description = u'',
537        required = False,
538        )
539
540    special_application = schema.Choice(
541        title = _(u'Special Application'),
542        source = SpecialApplicationSource(),
543        required = True,
544        )
545
546class IApplicantEdit(IApplicant):
547    """An applicant interface for editing.
548
549    Here we can repeat the fields from base data and set the
550    `required` and `readonly` attributes to True to further restrict
551    the data access. Or we can allow only certain certificates to be
552    selected by choosing the appropriate source.
553
554    We cannot omit fields here. This has to be done in the
555    respective form page.
556    """
557
558    email = schema.ASCIILine(
559        title = _(u'Email Address'),
560        required = True,
561        constraint=validate_email,
562        )
563    course1 = schema.Choice(
564        title = _(u'1st Choice Course of Study'),
565        source = AppCatCertificateSource(),
566        required = True,
567        )
568    course2 = schema.Choice(
569        title = _(u'2nd Choice Course of Study'),
570        source = AppCatCertificateSource(),
571        required = False,
572        )
573    course_admitted = schema.Choice(
574        title = _(u'Admitted Course of Study'),
575        source = CertificateSource(),
576        required = False,
577        readonly = True,
578        )
579    notice = schema.Text(
580        title = _(u'Notice'),
581        required = False,
582        readonly = True,
583        )
584
585IApplicantEdit['email'].order = IApplicantEdit[
586    'sex'].order
587
588class IApplicantUpdateByRegNo(IApplicant):
589    """Representation of an applicant.
590
591    Skip regular reg_number validation if reg_number is used for finding
592    the applicant object.
593    """
594    reg_number = schema.TextLine(
595        title = u'Registration Number',
596        required = False,
597        )
598
599class IApplicantRegisterUpdate(IApplicant):
600    """Representation of an applicant for first-time registration.
601
602    This interface is used when applicants use the registration page to
603    update their records.
604    """
605    reg_number = schema.TextLine(
606        title = u'Registration Number',
607        required = True,
608        )
609
610    firstname = schema.TextLine(
611        title = _(u'First Name'),
612        required = True,
613        )
614
615    email = schema.ASCIILine(
616        title = _(u'Email Address'),
617        required = True,
618        constraint=validate_email,
619        )
620
621class IApplicantOnlinePayment(IOnlinePayment):
622    """An applicant payment via payment gateways.
623
624    """
625
626    def doAfterApplicantPayment():
627        """Process applicant after payment was made.
628
629        """
630
631    def doAfterApplicantPaymentApproval():
632        """Process applicant after payment was approved.
633
634        """
635
636    def approveApplicantPayment():
637        """Approve payment and process applicant.
638
639        """
Note: See TracBrowser for help on using the repository browser.