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

:mod:`waeup.kofa.university.facultiescontainer` -- Faculty Containers
*********************************************************************

.. module:: waeup.kofa.university.facultiescontainer

Components that represent faculty containers.

.. :doctest:
.. :layer: waeup.kofa.testing.KofaUnitTestLayer


Content Classes (models and containers)
=======================================

:class:`FacultiesContainer`
---------------------------

.. class:: FacultiesContainer()

   Create a faculty container:

     >>> from waeup.kofa.university.facultiescontainer import FacultiesContainer
     >>> mycontainer = FacultiesContainer()
     >>> mycontainer
     <waeup.kofa.university.facultiescontainer.FacultiesContainer object at 0x...>

   Another way to create :class:`FacultiesContainer` instances is by asking
   for a factory called ``waeup.FacultiesContainer``. This way we can create a
   faculty without importing a class:

     >>> from zope.component import createObject
     >>> mycontainer = createObject(u'waeup.FacultiesContainer')
     >>> mycontainer
     <waeup.kofa.university.facultiescontainer.FacultiesContainer object at 0x...>

   :class:`FacultiesContainer` instances have the attributes required by the
   `IFacultiesContainer` interface:

     >>> from waeup.kofa.university.interfaces import IFacultiesContainer
     >>> IFacultiesContainer.providedBy(mycontainer)
     True

     >>> from zope.interface.verify import verifyObject
     >>> verifyObject(IFacultiesContainer, mycontainer)
     True

   .. method:: addFaculty(faculty)

      Add a faculty into this container. Added objects are checked and
      only `IFaculty` objects accepted:

        >>> mycontainer.addFaculty(object())
        Traceback (most recent call last):
        ...
        TypeError: FacultiesContainers contain only IFaculty instances

        >>> list(mycontainer.values())
        []

      Regular faculties are accepted:

        >>> from waeup.kofa.university.faculty import Faculty
        >>> mycontainer.addFaculty(Faculty(title='Physics',
        ...                                code='FP'))

        >>> list(mycontainer.items())
        [(u'FP', <waeup.kofa.university.faculty.Faculty object at 0x...>)]



Utilities
=========

:class:`AcademicsPlugin`
------------------------

.. class:: AcademicsPlugin()

   .. attribute:: grok.implements(IKofaPluggable)

   This plugin component tells under which name (``faculties``) an
   instance of academics stuff should be created in plain Kofa
   instances. It also tells the factory name for FacultiesContainer
   instances, which serve as root object for academics stuff in Kofa apps.


:class:`FacultiesContainerFactory`
----------------------------------

.. class:: FacultiesContainerFactory()

   .. attribute:: grok.name(u'waeup.FacultiesContainer')

   .. attribute:: grok.implements(IFactoryContainer)

   A named utility to deliver new instances of :class:`FacultiesContainer`
   without the need to import the implementation before:

     >>> from zope.component import createObject
     >>> mycontainer = createObject(u'waeup.FacultiesContainer')
     >>> mycontainer
     <waeup.kofa.university.facultiescontainer.FacultiesContainer object at 0x...>

   The factory complies with the specifications from the
   :class:`IFactory` insterface:

     >>> from zope.interface.verify import verifyClass
     >>> from zope.component.interfaces import IFactory
     >>> from waeup.kofa.university.facultiescontainer import (
     ...   FacultiesContainerFactory)
     >>> verifyClass(IFactory, FacultiesContainerFactory)
     True

   This means also, that we can get the interfaces of the created
   object from the factory:

     >>> fac_container_factory = FacultiesContainerFactory()
     >>> fac_container_factory.getInterfaces()
     <implementedBy waeup.kofa.university.facultiescontainer.FacultiesContainer>

Examples
========

We can easily create `FacultiesContainers`:

    >>> from waeup.kofa.university.facultiescontainer import FacultiesContainer
    >>> mycontainer = FacultiesContainer()

Faculty containers provide `IFacultiesContainer`:

    >>> from waeup.kofa.university.interfaces import IFacultiesContainer
    >>> IFacultiesContainer.providedBy(mycontainer)
    True

Another way to get a faculty container -- without importing the class
-- is via factories. We registered a factory for faculty containers
under the name ``waeup.facultiescontainer``:

    >>> from zope.component import createObject
    >>> createObject(u'waeup.FacultiesContainer')
    <waeup.kofa.university.facultiescontainer.FacultiesContainer object at 0x...>

This way we get a thing that implements IFacultiesContainer without
imports or similar.

We can be sure, that the full interface is supported by the
FacultiesContainer class::

    >>> from zope.interface.verify import verifyClass
    >>> verifyClass(IFacultiesContainer, FacultiesContainer)
    True


Storing things in faculty containers
====================================

We can, of course, store things in a faculty container. But when we
really store an object, then it must be a faculty::

    >>> mycontainer.addFaculty(42)
    Traceback (most recent call last):
    ...
    TypeError: FacultiesContainers contain only IFaculty instances

Okay, so we have to get a faculty first::

    >>> from waeup.kofa.university.faculty import Faculty
    >>> myfaculty = Faculty()

We can add this faculty to our container::

    >>> mycontainer.addFaculty(myfaculty)

We get back the key, under which the faculty was stored. It will be
some string, but there is no guarantee at all, how this key looks
like. It might be a string of integers, a name or whatever; you cannot
know before.