source: main/waeup.sirp/trunk/src/waeup/sirp/applicants/interfaces.py @ 7737

Last change on this file since 7737 was 7708, checked in by Henrik Bettermann, 13 years ago

Start internationalization of applicants package. Store description as reST dictionary like frontpage in browsers.

  • Property svn:keywords set to Id
File size: 19.3 KB
Line 
1## $Id: interfaces.py 7708 2012-02-27 11:52:23Z 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"""
20
21from grokcore.content.interfaces import IContainer
22
23from zope import schema
24from zope.interface import Interface, Attribute, implements, directlyProvides
25from zope.component import getUtilitiesFor, queryUtility, getUtility
26from zope.catalog.interfaces import ICatalog
27from zope.schema.interfaces import (
28    ValidationError, ISource, IContextSourceBinder)
29from zc.sourcefactory.basic import BasicSourceFactory
30from zc.sourcefactory.contextual import BasicContextualSourceFactory
31from waeup.sirp.schema import TextLineChoice
32from waeup.sirp.interfaces import (
33    ISIRPObject, year_range, validate_email, academic_sessions_vocab)
34from waeup.sirp.interfaces import MessageFactory as _
35from waeup.sirp.university.vocabularies import (
36    course_levels, AppCatSource)
37from waeup.sirp.students.vocabularies import (
38    lgas_vocab, CertificateSource, GenderSource)
39from waeup.sirp.payments.interfaces import IOnlinePayment
40
41#: Maximum upload size for applicant passport photographs (in bytes)
42MAX_UPLOAD_SIZE = 1024 * 20
43
44class RegNumInSource(ValidationError):
45    """Registration number exists already
46    """
47    # The docstring of ValidationErrors is used as error description
48    # by zope.formlib.
49    pass
50
51class RegNumberSource(object):
52    implements(ISource)
53    cat_name = 'applicants_catalog'
54    field_name = 'reg_number'
55    validation_error = RegNumInSource
56    def __init__(self, context):
57        self.context = context
58        return
59
60    def __contains__(self, value):
61        cat = queryUtility(ICatalog, self.cat_name)
62        if cat is None:
63            return True
64        kw = {self.field_name: (value, value)}
65        results = cat.searchResults(**kw)
66        for entry in results:
67            if entry.applicant_id != self.context.applicant_id:
68                # XXX: sources should simply return False.
69                #      But then we get some stupid error message in forms
70                #      when validation fails.
71                raise self.validation_error(value)
72                #return False
73        return True
74
75def contextual_reg_num_source(context):
76    source = RegNumberSource(context)
77    return source
78directlyProvides(contextual_reg_num_source, IContextSourceBinder)
79
80class AppCatCertificateSource(CertificateSource):
81    """An application certificate source delivers all courses which belong to
82    a certain application_category.
83    """
84    def getValues(self, context):
85        # appliction category not available when certificate was deleted.
86        # shouldn't that info be part of applicant info instead?
87        # when we cannot determine the appcat, we will display all courses.
88        appcat = getattr(getattr(context, '__parent__', None),
89                         'application_category', None)
90        catalog = getUtility(ICatalog, name='certificates_catalog')
91        result = catalog.searchResults(
92            application_category=(appcat,appcat))
93        result = sorted(result, key=lambda value: value.code)
94        curr_course = context.course1
95        if curr_course is not None and curr_course not in result:
96            # display also current course even if it is not catalogued
97            # (any more)
98            result = [curr_course,] + result
99        return result
100
101class ApplicationTypeSource(BasicContextualSourceFactory):
102    """An application type source delivers screening types defined in the
103    portal.
104    """
105    def getValues(self, context):
106        appcats_dict = getUtility(
107            IApplicantsUtils).getApplicationTypeDict()
108        return sorted(appcats_dict.keys())
109
110    def getToken(self, context, value):
111        return value
112
113    def getTitle(self, context, value):
114        appcats_dict = getUtility(
115            IApplicantsUtils).getApplicationTypeDict()
116        return appcats_dict[value][0]
117
118# Maybe Uniben still needs this ...
119#class ApplicationPinSource(BasicContextualSourceFactory):
120#    """An application pin source delivers PIN prefixes for application
121#    defined in the portal.
122#    """
123#    def getValues(self, context):
124#        apppins_dict = getUtility(
125#            IApplicantsUtils).getApplicationTypeDict()
126#        return sorted(appcats_dict.keys())
127#
128#    def getToken(self, context, value):
129#        return value
130#
131#    def getTitle(self, context, value):
132#        apppins_dict = getUtility(
133#            IApplicantsUtils).getApplicationTypeDict()
134#        return u"%s (%s)" % (
135#            apppins_dict[value][1],self.apppins_dict[value][0])
136
137class ApplicantContainerProviderSource(BasicSourceFactory):
138    """A source offering all available applicants container types.
139
140    The values returned by this source are names of utilities that can
141    create :class:`ApplicantContainer` instances. So, if you get a
142    name like ``'myactype'`` from this source, then you can do:
143
144      >>> from zope.component import getUtility
145      >>> p = getUtility(IApplicantsContainerProvider, name=myactype)
146      >>> my_applicants_container = p.factory()
147
148    Or you can access class-attributes like
149
150      >>> my_applicants_container.container_title
151      'Pretty'
152
153    """
154    def getValues(self):
155        """Returns a list of ``(<name>, <provider>)`` tuples.
156
157        Here ``<name>`` is the name under which an
158        :class:``ApplicantContainerProvider`` was registered as a
159        utility and ``<provider>`` is the utility itself.
160        """
161        return getUtilitiesFor(IApplicantsContainerProvider)
162
163    def getToken(self, value):
164        """Return the name of the ``(<name>, <provider>)`` tuple.
165        """
166        return value[0]
167
168    def getTitle(self, value):
169        """Get a 'title - description' string for a container type.
170        """
171        factory = value[1].factory
172        return "%s - %s" % (
173            factory.container_title, factory.container_description)
174
175class IApplicantsUtils(Interface):
176    """A collection of methods which are subject to customization.
177    """
178    pass
179
180class IApplicantsRoot(ISIRPObject, IContainer):
181    """A container for university applicants containers.
182    """
183    pass
184
185class IApplicantsContainer(ISIRPObject):
186    """An applicants container contains university applicants.
187
188    """
189
190    container_title = Attribute(
191        u'classattribute: title for type of container')
192    container_description = Attribute(
193        u'classattribute: description for type of container')
194
195
196    code = schema.TextLine(
197        title = _(u'Code'),
198        default = u'-',
199        required = True,
200        readonly = True,
201        )
202
203    title = schema.TextLine(
204        title = _(u'Title'),
205        required = True,
206        default = u'-',
207        readonly = True,
208        )
209
210    prefix = schema.Choice(
211        title = _(u'Application Target'),
212        required = True,
213        default = None,
214        source = ApplicationTypeSource(),
215        readonly = True,
216        )
217
218    entry_level = schema.Choice(
219        title = _(u'Entry Level'),
220        vocabulary = course_levels,
221        default = 100,
222        required = True,
223        )
224
225    year = schema.Choice(
226        title = _(u'Year of Entrance'),
227        required = True,
228        default = None,
229        values = year_range(),
230        readonly = True,
231        )
232
233    provider = schema.Choice(
234        title = _(u'Applicants Container Type'),
235        required = True,
236        default = None,
237        source = ApplicantContainerProviderSource(),
238        readonly = True,
239        )
240
241    # Maybe Uniben still needs this ...
242    #ac_prefix = schema.Choice(
243    #    title = u'Activation code prefix',
244    #    required = True,
245    #    default = None,
246    #    source = ApplicationPinSource(),
247    #    )
248
249    application_category = schema.Choice(
250        title = _(u'Category for the grouping of certificates'),
251        required = True,
252        default = None,
253        source = AppCatSource(),
254        )
255
256    description = schema.Text(
257        title = _(u'Human readable description in reST format'),
258        required = False,
259        default = u'''This text can been seen by anonymous users.
260Here we put mult-lingual information about the study courses provided, the application procedure and deadlines.
261>>de<<
262Dieser Text kann von anonymen Benutzern gelesen werden.
263Hier koennen mehrsprachige Informationen fuer Antragsteller hinterlegt werden.'''
264        )
265
266    description_dict = schema.Dict(
267        title = u'Content as language dictionary with values in html format',
268        required = False,
269        default = {},
270        )
271
272    startdate = schema.Date(
273        title = _(u'Application Start Date'),
274        required = False,
275        default = None,
276        )
277
278    enddate = schema.Date(
279        title = _(u'Application Closing Date'),
280        required = False,
281        default = None,
282        )
283
284    strict_deadline = schema.Bool(
285        title = _(u'Forbid additions after deadline (enddate)'),
286        required = True,
287        default = True,
288        )
289
290    def archive(id=None):
291        """Create on-dist archive of applicants stored in this term.
292
293        If id is `None`, all applicants are archived.
294
295        If id contains a single id string, only the respective
296        applicants are archived.
297
298        If id contains a list of id strings all of the respective
299        applicants types are saved to disk.
300        """
301
302    def clear(id=None, archive=True):
303        """Remove applicants of type given by 'id'.
304
305        Optionally archive the applicants.
306
307        If id is `None`, all applicants are archived.
308
309        If id contains a single id string, only the respective
310        applicants are archived.
311
312        If id contains a list of id strings all of the respective
313        applicant types are saved to disk.
314
315        If `archive` is ``False`` none of the archive-handling is done
316        and respective applicants are simply removed from the
317        database.
318        """
319
320class IApplicantsContainerAdd(IApplicantsContainer):
321    """An applicants container contains university applicants.
322    """
323    prefix = schema.Choice(
324        title = _(u'Application Target'),
325        required = True,
326        default = None,
327        source = ApplicationTypeSource(),
328        readonly = False,
329        )
330
331    year = schema.Choice(
332        title = _(u'Year of Entrance'),
333        required = True,
334        default = None,
335        values = year_range(),
336        readonly = False,
337        )
338
339    provider = schema.Choice(
340        title = _(u'Applicants Container Type'),
341        required = True,
342        default = None,
343        source = ApplicantContainerProviderSource(),
344        readonly = False,
345        )
346
347IApplicantsContainerAdd[
348    'prefix'].order =  IApplicantsContainer['prefix'].order
349IApplicantsContainerAdd[
350    'year'].order =  IApplicantsContainer['year'].order
351IApplicantsContainerAdd[
352    'provider'].order =  IApplicantsContainer['provider'].order
353
354class IApplicantBaseData(ISIRPObject):
355    """The data for an applicant.
356
357    This is a base interface with no field
358    required. For use with importers, forms, etc., please use one of
359    the derived interfaces below, which set more fields to required
360    state, depending on use-case.
361
362    This base interface is also implemented by the StudentApplication
363    class in the students package. Thus, these are the data which are saved
364    after admission.
365    """
366
367    applicant_id = schema.TextLine(
368        title = _(u'Applicant Id'),
369        required = False,
370        readonly = False,
371        )
372    reg_number = TextLineChoice(
373        title = _(u'JAMB Registration Number'),
374        readonly = False,
375        required = True,
376        default = None,
377        source = contextual_reg_num_source,
378        )
379    #access_code = schema.TextLine(
380    #    title = u'Activation Code',
381    #    required = False,
382    #    readonly = True,
383    #    )
384    firstname = schema.TextLine(
385        title = _(u'First Name'),
386        required = True,
387        )
388    middlename = schema.TextLine(
389        title = _(u'Middle Name'),
390        required = False,
391        )
392    lastname = schema.TextLine(
393        title = _(u'Last Name (Surname)'),
394        required = True,
395        )
396    date_of_birth = schema.Date(
397        title = _(u'Date of Birth'),
398        required = True,
399        )
400    lga = schema.Choice(
401        source = lgas_vocab,
402        title = _(u'State/LGA'),
403        default = 'foreigner',
404        required = True,
405        )
406    sex = schema.Choice(
407        title = _(u'Sex'),
408        source = GenderSource(),
409        default = u'm',
410        required = True,
411        )
412    email = schema.ASCIILine(
413        title = _(u'Email Address'),
414        required = True,
415        constraint=validate_email,
416        )
417    phone = schema.TextLine(
418        title = _(u'Phone'),
419        description = u'',
420        required = False,
421        )
422    course1 = schema.Choice(
423        title = _(u'1st Choice Course of Study'),
424        source = CertificateSource(),
425        required = True,
426        )
427    course2 = schema.Choice(
428        title = _(u'2nd Choice Course of Study'),
429        source = CertificateSource(),
430        required = False,
431        )
432
433    #
434    # Data to be imported after screening
435    #
436    screening_score = schema.Int(
437        title = _(u'Screening Score'),
438        required = False,
439        )
440    screening_venue = schema.TextLine(
441        title = _(u'Screening Venue'),
442        required = False,
443        )
444    course_admitted = schema.Choice(
445        title = _(u'Admitted Course of Study'),
446        source = CertificateSource(),
447        default = None,
448        required = False,
449        )
450    notice = schema.Text(
451        title = _(u'Notice'),
452        required = False,
453        )
454
455class IApplicantProcessData(IApplicantBaseData):
456    """An applicant.
457
458    Here we add process attributes and methods to the base data.
459    """
460
461    history = Attribute('Object history, a list of messages.')
462    state = Attribute('The application state of an applicant')
463    display_fullname = Attribute('The fullname of an applicant')
464    application_date = Attribute('Date of submission, used for export only')
465    password = Attribute('Encrypted password of a applicant')
466    application_number = Attribute('The key under which the record is stored')
467
468    def loggerInfo(ob_class, comment):
469        """Adds an INFO message to the log file
470        """
471
472    student_id = schema.TextLine(
473        title = _(u'Student Id'),
474        required = False,
475        readonly = False,
476        )
477    locked = schema.Bool(
478        title = _(u'Form locked'),
479        default = False,
480        )
481
482class IApplicant(IApplicantProcessData):
483    """An applicant.
484
485    This is basically the applicant base data. Here we repeat the
486    fields from base data if we have to set the `required` attribute
487    to True (which is the default).
488    """
489
490class IApplicantEdit(IApplicantProcessData):
491    """An applicant.
492
493    Here we can repeat the fields from base data and set the
494    `required` and `readonly` attributes to True to further restrict
495    the data access. Or we can allow only certain certificates to be
496    selected by choosing the appropriate source.
497
498    We cannot omit fields here. This has to be done in the
499    respective form page.
500    """
501
502    course1 = schema.Choice(
503        title = _(u'1st Choice Course of Study'),
504        source = AppCatCertificateSource(),
505        required = True,
506        )
507    course2 = schema.Choice(
508        title = _(u'2nd Choice Course of Study'),
509        source = AppCatCertificateSource(),
510        required = False,
511        )
512    screening_score = schema.Int(
513        title = _(u'Screening Score'),
514        required = False,
515        readonly = True,
516        )
517    screening_venue = schema.TextLine(
518        title = _(u'Screening Venue'),
519        required = False,
520        readonly = True,
521        )
522    course_admitted = schema.Choice(
523        title = _(u'Admitted Course of Study'),
524        source = CertificateSource(),
525        default = None,
526        required = False,
527        readonly = True,
528        )
529    notice = schema.Text(
530        title = _(u'Notice'),
531        required = False,
532        readonly = True,
533        )
534
535    def createStudent():
536        """Create a student object from applicatnt data
537        and copy applicant object.
538        """
539
540class IApplicantUpdateByRegNo(IApplicant):
541    """Representation of an applicant.
542
543    Skip regular reg_number validation if reg_number is used for finding
544    the applicant object.
545    """
546    reg_number = schema.TextLine(
547        title = u'Registration Number',
548        default = None,
549        required = False,
550        )
551
552class IApplicantOnlinePayment(IOnlinePayment):
553    """An applicant payment via payment gateways.
554
555    """
556    p_year = schema.Choice(
557        title = _(u'Payment Session'),
558        source = academic_sessions_vocab,
559        required = False,
560        )
561
562IApplicantOnlinePayment['p_year'].order = IApplicantOnlinePayment[
563    'p_year'].order
564
565class IApplicantsContainerProvider(Interface):
566    """A provider for applicants containers.
567
568    Applicants container providers are meant to be looked up as
569    utilities. This way we can find all applicant container types
570    defined somewhere.
571
572    Each applicants container provider registered as utility provides
573    one container type and one should be able to call the `factory`
574    attribute to create an instance of the requested container type.
575
576    .. THE FOLLOWING SHOULD GO INTO SPHINX DOCS (and be tested)
577
578    Samples:
579
580    Given, you had an IApplicantsContainer implementation somewhere
581    and you would like to make it findable on request, then you would
582    normally create an appropriate provider utility like this::
583
584      import grok
585      from waeup.sirp.applicants.interfaces import IApplicantsContainerProvider
586
587      class MyContainerProvider(grok.GlobalUtility):
588          grok.implements(IApplicantsContainerProvider)
589          grok.name('MyContainerProvider') # Must be unique
590          factory = MyContainer # A class implementing IApplicantsContainer
591                                # or derivations thereof.
592
593    This utility would be registered on startup and could then be used
594    like this:
595
596      >>> from zope.component import getAllUtilitiesRegisteredFor
597      >>> from waeup.sirp.applicants.interfaces import (
598      ...     IApplicantsContainerProvider)
599      >>> all_providers = getAllUtilitiesRegisteredFor(
600      ...     IApplicantsContainerProvider)
601      >>> all_providers
602      [<MyContainerProvider object at 0x...>]
603
604    You could look up this specific provider by name:
605
606      >>> from zope.component import getUtility
607      >>> p = getUtility(IApplicantsContainerProvider, name='MyProvider')
608      >>> p
609      <MyContainerProvider object at 0x...>
610
611    An applicants container would then be created like this:
612
613      >>> provider = all_providers[0]
614      >>> container = provider.factory()
615      >>> container
616      <MyContainer object at 0x...>
617
618    """
619    factory = Attribute("A class that can create instances of the "
620                        "requested container type")
Note: See TracBrowser for help on using the repository browser.