:mod:`waeup.ikoba.app` -- central components for Ikoba
****************************************************

.. :doctest:
.. :layer: waeup.ikoba.testing.IkobaUnitTestLayer

.. module:: waeup.ikoba.app

.. class:: Institution

  The main Ikoba application object is given with
  :class:`Institution`. It provides the main containers as faculties,
  hostels, etc.

  .. attribute:: name

     A string. The name of a institution.

  .. attribute:: faculties

     An arbitrary object containing "faculties". In the case of
     `Institution` it is a container of type
     `waeup.ikoba.interfaces.IFacultiesContainer`.


Creating `Institution` instances
===============================

As :class:`Institution` instances make use of the Zope Component
Architecture (ZCA), we have to setup the basic component registries,
before we can create instances. We do this by simply grokking the
whole :mod:`waeup` package. This way all interfaces, utilities and adapters
defined in the package are looked up and registered with the global
registries (this is done by the testlayer automatically).

Now we can import the :class:`Institution` class and create an
instance:

    >>> from waeup.ikoba.app import Institution
    >>> myinstitution = Institution()
    >>> myinstitution
    <waeup.ikoba.app.Institution object at 0x...>

Instances of `Institution` comply with the interface
`waeup.ikoba.interfaces.IInstitution`:

    >>> from zope.interface.verify import verifyClass
    >>> from waeup.ikoba.interfaces import IInstitution
    >>> verifyClass(IInstitution, Institution)
    True

A freshly created instance provides the attributes promised by the
interface:

    >>> from waeup.ikoba.app import Institution
    >>> myinstitution = Institution()
    >>> myinstitution['configuration'].name
    u'Sample Institution'

  >>> myinstitution['users']
  <waeup.ikoba.userscontainer.UsersContainer object at 0x...>

  >>> myinstitution['datacenter']
  <waeup.ikoba.datacenter.DataCenter object at 0x...>

  >>> myinstitution['configuration']
  <waeup.ikoba.configuration.ConfigurationContainer object at 0x...>


Ikoba plugins
============

waeup.ikoba provides an API to 'plugin' components. Things that should
be setup at creation time of a Ikoba application can indicate
that by providing a utility providing IIkobaPlugin.

The plugins are looked up by an created app, which then will call the
``setup()`` method of each plugin.

   >>> from waeup.ikoba.interfaces import IIkobaPluggable
   >>> from zope.component import getAdapters, getUtilitiesFor
   >>> sorted(list(getUtilitiesFor(IIkobaPluggable)))
   [(u'mandates', <waeup.ikoba.mandates.container.MandatesPlugin ...)]


We can provide a new plugin like this:

   >>> import grok
   >>> from waeup.ikoba.interfaces import IIkobaPluggable
   >>> class MyPlugin(grok.GlobalUtility):
   ...   grok.implements(IIkobaPluggable)
   ...   def setup(self, site, name, logger):
   ...     print "Setup was called for"
   ...     print site
   ...   def update(self, site, name, logger):
   ...     pass

When we register the plugin

   >>> grok.testing.grok_component('MyPlugin', MyPlugin)
   True

and setup a new Ikoba instance, we will get a message:

   >>> from waeup.ikoba.app import Institution
   >>> site = Institution()
   Setup was called for
   <waeup.ikoba.app.Institution object at 0x...>

Apparently the plugin can do with the Institution object whatever it
likes. That's what plugins are for.