source: main/waeup.ikoba/branches/uli-fake-gw-provider/src/waeup/ikoba/app.txt @ 12646

Last change on this file since 12646 was 12209, checked in by Henrik Bettermann, 10 years ago

Take new plugin into considerartion.

File size: 3.3 KB
Line 
1:mod:`waeup.ikoba.app` -- central components for Ikoba
2******************************************************
3
4.. :doctest:
5.. :layer: waeup.ikoba.testing.IkobaUnitTestLayer
6
7.. module:: waeup.ikoba.app
8
9.. class:: Company
10
11  The main Ikoba application object is given with
12  :class:`Company`. It provides the main containers as faculties,
13  hostels, etc.
14
15  .. attribute:: name
16
17     A string. The name of a company.
18
19  .. attribute:: faculties
20
21     An arbitrary object containing "faculties". In the case of
22     `Company` it is a container of type
23     `waeup.ikoba.interfaces.IFacultiesContainer`.
24
25
26Creating `Company` instances
27============================
28
29As :class:`Company` 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:`Company` class and create an
37instance:
38
39    >>> from waeup.ikoba.app import Company
40    >>> mycompany = Company()
41    >>> mycompany
42    <waeup.ikoba.app.Company object at 0x...>
43
44Instances of `Company` comply with the interface
45`waeup.ikoba.interfaces.ICompany`:
46
47    >>> from zope.interface.verify import verifyClass
48    >>> from waeup.ikoba.interfaces import ICompany
49    >>> verifyClass(ICompany, Company)
50    True
51
52A freshly created instance provides the attributes promised by the
53interface:
54
55    >>> from waeup.ikoba.app import Company
56    >>> mycompany = Company()
57    >>> mycompany['configuration'].name
58    u'Sample Company'
59
60  >>> mycompany['users']
61  <waeup.ikoba.userscontainer.UsersContainer object at 0x...>
62
63  >>> mycompany['datacenter']
64  <waeup.ikoba.datacenter.DataCenter object at 0x...>
65
66  >>> mycompany['configuration']
67  <waeup.ikoba.configuration.ConfigurationContainer object at 0x...>
68
69
70Ikoba plugins
71=============
72
73waeup.ikoba provides an API to 'plugin' components. Things that should
74be setup at creation time of a Ikoba application can indicate
75that by providing a utility providing IIkobaPlugin.
76
77The plugins are looked up by an created app, which then will call the
78``setup()`` method of each plugin.
79
80   >>> from waeup.ikoba.interfaces import IIkobaPluggable
81   >>> from zope.component import getAdapters, getUtilitiesFor
82   >>> sorted(list(getUtilitiesFor(IIkobaPluggable)))
83   [(u'documents', <waeup.ikoba.documents.container.DocumentsPlugin ...)]
84
85
86We can provide a new plugin like this:
87
88   >>> import grok
89   >>> from waeup.ikoba.interfaces import IIkobaPluggable
90   >>> class MyPlugin(grok.GlobalUtility):
91   ...   grok.implements(IIkobaPluggable)
92   ...   def setup(self, site, name, logger):
93   ...     print "Setup was called for"
94   ...     print site
95   ...   def update(self, site, name, logger):
96   ...     pass
97
98When we register the plugin
99
100   >>> grok.testing.grok_component('MyPlugin', MyPlugin)
101   True
102
103and setup a new Ikoba instance, we will get a message:
104
105   >>> from waeup.ikoba.app import Company
106   >>> site = Company()
107   Setup was called for
108   <waeup.ikoba.app.Company object at 0x...>
109
110Apparently the plugin can do with the Company object whatever it
111likes. That's what plugins are for.
Note: See TracBrowser for help on using the repository browser.