source: main/waeup.kofa/branches/0.2/src/waeup/kofa/university/facultiescontainer.txt @ 15185

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

KOFA -> Kofa

File size: 5.6 KB
Line 
1:mod:`waeup.kofa.university.facultiescontainer` -- Faculty Containers
2*********************************************************************
3
4.. module:: waeup.kofa.university.facultiescontainer
5
6Components that represent faculty containers.
7
8.. :doctest:
9.. :layer: waeup.kofa.testing.KofaUnitTestLayer
10
11
12Content Classes (models and containers)
13=======================================
14
15:class:`FacultiesContainer`
16---------------------------
17
18.. class:: FacultiesContainer()
19
20   Create a faculty container:
21
22     >>> from waeup.kofa.university.facultiescontainer import FacultiesContainer
23     >>> mycontainer = FacultiesContainer()
24     >>> mycontainer
25     <waeup.kofa.university.facultiescontainer.FacultiesContainer object at 0x...>
26
27   Another way to create :class:`FacultiesContainer` instances is by asking
28   for a factory called ``waeup.FacultiesContainer``. This way we can create a
29   faculty without importing a class:
30
31     >>> from zope.component import createObject
32     >>> mycontainer = createObject(u'waeup.FacultiesContainer')
33     >>> mycontainer
34     <waeup.kofa.university.facultiescontainer.FacultiesContainer object at 0x...>
35
36   :class:`FacultiesContainer` instances have the attributes required by the
37   `IFacultiesContainer` interface:
38
39     >>> from waeup.kofa.university.interfaces import IFacultiesContainer
40     >>> IFacultiesContainer.providedBy(mycontainer)
41     True
42
43     >>> from zope.interface.verify import verifyObject
44     >>> verifyObject(IFacultiesContainer, mycontainer)
45     True
46
47   .. method:: addFaculty(faculty)
48
49      Add a faculty into this container. Added objects are checked and
50      only `IFaculty` objects accepted:
51
52        >>> mycontainer.addFaculty(object())
53        Traceback (most recent call last):
54        ...
55        TypeError: FacultiesContainers contain only IFaculty instances
56
57        >>> list(mycontainer.values())
58        []
59
60      Regular faculties are accepted:
61
62        >>> from waeup.kofa.university.faculty import Faculty
63        >>> mycontainer.addFaculty(Faculty(title='Physics',
64        ...                                code='FP'))
65
66        >>> list(mycontainer.items())
67        [(u'FP', <waeup.kofa.university.faculty.Faculty object at 0x...>)]
68
69
70
71Utilities
72=========
73
74:class:`AcademicsPlugin`
75------------------------
76
77.. class:: AcademicsPlugin()
78
79   .. attribute:: grok.implements(IKofaPluggable)
80
81   This plugin component tells under which name (``faculties``) an
82   instance of academics stuff should be created in plain Kofa
83   instances. It also tells the factory name for FacultiesContainer
84   instances, which serve as root object for academics stuff in Kofa apps.
85
86
87:class:`FacultiesContainerFactory`
88----------------------------------
89
90.. class:: FacultiesContainerFactory()
91
92   .. attribute:: grok.name(u'waeup.FacultiesContainer')
93
94   .. attribute:: grok.implements(IFactoryContainer)
95
96   A named utility to deliver new instances of :class:`FacultiesContainer`
97   without the need to import the implementation before:
98
99     >>> from zope.component import createObject
100     >>> mycontainer = createObject(u'waeup.FacultiesContainer')
101     >>> mycontainer
102     <waeup.kofa.university.facultiescontainer.FacultiesContainer object at 0x...>
103
104   The factory complies with the specifications from the
105   :class:`IFactory` insterface:
106
107     >>> from zope.interface.verify import verifyClass
108     >>> from zope.component.interfaces import IFactory
109     >>> from waeup.kofa.university.facultiescontainer import (
110     ...   FacultiesContainerFactory)
111     >>> verifyClass(IFactory, FacultiesContainerFactory)
112     True
113
114   This means also, that we can get the interfaces of the created
115   object from the factory:
116
117     >>> fac_container_factory = FacultiesContainerFactory()
118     >>> fac_container_factory.getInterfaces()
119     <implementedBy waeup.kofa.university.facultiescontainer.FacultiesContainer>
120
121Examples
122========
123
124We can easily create `FacultiesContainers`:
125
126    >>> from waeup.kofa.university.facultiescontainer import FacultiesContainer
127    >>> mycontainer = FacultiesContainer()
128
129Faculty containers provide `IFacultiesContainer`:
130
131    >>> from waeup.kofa.university.interfaces import IFacultiesContainer
132    >>> IFacultiesContainer.providedBy(mycontainer)
133    True
134
135Another way to get a faculty container -- without importing the class
136-- is via factories. We registered a factory for faculty containers
137under the name ``waeup.facultiescontainer``:
138
139    >>> from zope.component import createObject
140    >>> createObject(u'waeup.FacultiesContainer')
141    <waeup.kofa.university.facultiescontainer.FacultiesContainer object at 0x...>
142
143This way we get a thing that implements IFacultiesContainer without
144imports or similar.
145
146We can be sure, that the full interface is supported by the
147FacultiesContainer class::
148
149    >>> from zope.interface.verify import verifyClass
150    >>> verifyClass(IFacultiesContainer, FacultiesContainer)
151    True
152
153
154Storing things in faculty containers
155====================================
156
157We can, of course, store things in a faculty container. But when we
158really store an object, then it must be a faculty::
159
160    >>> mycontainer.addFaculty(42)
161    Traceback (most recent call last):
162    ...
163    TypeError: FacultiesContainers contain only IFaculty instances
164
165Okay, so we have to get a faculty first::
166
167    >>> from waeup.kofa.university.faculty import Faculty
168    >>> myfaculty = Faculty()
169
170We can add this faculty to our container::
171
172    >>> mycontainer.addFaculty(myfaculty)
173
174We get back the key, under which the faculty was stored. It will be
175some string, but there is no guarantee at all, how this key looks
176like. It might be a string of integers, a name or whatever; you cannot
177know before.
178
Note: See TracBrowser for help on using the repository browser.