source: main/waeup.kofa/trunk/src/waeup/kofa/app.txt @ 11154

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

KOFA -> Kofa

File size: 4.3 KB
Line 
1:mod:`waeup.kofa.app` -- central components for Kofa
2****************************************************
3
4.. :doctest:
5.. :layer: waeup.kofa.testing.KofaUnitTestLayer
6
7.. module:: waeup.kofa.app
8
9.. class:: University
10
11  The main Kofa application object is given with
12  :class:`University`. It provides the main containers as faculties,
13  hostels, etc.
14
15  .. attribute:: name
16
17     A string. The name of a university.
18
19  .. attribute:: faculties
20
21     An arbitrary object containing "faculties". In the case of
22     `University` it is a container of type
23     `waeup.kofa.interfaces.IFacultiesContainer`.
24
25
26Creating `University` instances
27===============================
28
29As :class:`University` instances make use of the Zope Component
30Architecture (ZCA), we have to setup the basic component registries,
31before we can create instances. We do this by simply grokking the
32whole :mod:`waeup` package. This way all interfaces, utilities and adapters
33defined in the package are looked up and registered with the global
34registries (this is done by the testlayer automatically).
35
36Now we can import the :class:`University` class and create an
37instance:
38
39    >>> from waeup.kofa.app import University
40    >>> myuniversity = University()
41    >>> myuniversity
42    <waeup.kofa.app.University object at 0x...>
43
44Instances of `University` comply with the interface
45`waeup.kofa.interfaces.IUniversity`:
46
47    >>> from zope.interface.verify import verifyClass
48    >>> from waeup.kofa.interfaces import IUniversity
49    >>> verifyClass(IUniversity, University)
50    True
51
52A freshly created instance provides the attributes promised by the
53interface:
54
55    >>> from waeup.kofa.app import University
56    >>> myuniversity = University()
57    >>> myuniversity['configuration'].name
58    u'Sample University'
59
60    >>> myuniversity['faculties']
61    <waeup.kofa.university.facultiescontainer.FacultiesContainer object at 0x...>
62
63  >>> myuniversity['students']
64  <waeup.kofa.students.container.StudentsContainer object at 0x...>
65
66  >>> myuniversity['users']
67  <waeup.kofa.userscontainer.UsersContainer object at 0x...>
68
69  >>> myuniversity['datacenter']
70  <waeup.kofa.datacenter.DataCenter object at 0x...>
71
72  >>> myuniversity['configuration']
73  <waeup.kofa.configuration.ConfigurationContainer object at 0x...>
74
75We can export universities. For this we lookup an appropriate exporter
76first::
77
78  >>> from waeup.kofa.interfaces import IKofaExporter
79  >>> exporter = IKofaExporter(myuniversity)
80  >>> exporter
81  <waeup.kofa.utils.importexport.Exporter object at 0x...>
82
83Now we can trigger the export::
84
85  >>> exporter.export()
86  <cStringIO.StringO object at 0x...>
87
88We can also get an XML representation as file. If we do not provide a
89filepath, we will get an instance of `cStringIO.StringIO`, i.e. a
90memory file::
91
92  >>> from waeup.kofa.interfaces import IKofaXMLExporter
93  >>> exporter = IKofaXMLExporter(myuniversity)
94  >>> f = exporter.export()
95  >>> f
96  <cStringIO.StringO object at 0x...>
97
98  >>> print f.read()
99  <?xml version="1.0" encoding="utf-8" ?>
100  <pickle>
101    <initialized_object id="...">
102  ...
103  </pickle>
104
105Kofa plugins
106============
107
108waeup.kofa provides an API to 'plugin' components. Things that should
109be setup at creation time of a Kofa application can indicate
110that by providing a utility providing IKofaPlugin.
111
112The plugins are looked up by an created app, which then will call the
113``setup()`` method of each plugin.
114
115   >>> from waeup.kofa.interfaces import IKofaPluggable
116   >>> from zope.component import getAdapters, getUtilitiesFor
117   >>> sorted(list(getUtilitiesFor(IKofaPluggable)))
118   [(u'accesscodes', <waeup.kofa.accesscodes...AccessCodePlugin ...)]
119
120
121We can provide a new plugin like this:
122
123   >>> import grok
124   >>> from waeup.kofa.interfaces import IKofaPluggable
125   >>> class MyPlugin(grok.GlobalUtility):
126   ...   grok.implements(IKofaPluggable)
127   ...   def setup(self, site, name, logger):
128   ...     print "Setup was called for"
129   ...     print site
130   ...   def update(self, site, name, logger):
131   ...     pass
132
133When we register the plugin
134
135   >>> grok.testing.grok_component('MyPlugin', MyPlugin)
136   True
137
138and setup a new Kofa instance, we will get a message:
139
140   >>> from waeup.kofa.app import University
141   >>> site = University()
142   Setup was called for
143   <waeup.kofa.app.University object at 0x...>
144
145Apparently the plugin can do with the University object whatever it
146likes. That's what plugins are for.
Note: See TracBrowser for help on using the repository browser.