source: main/waeup.sirp/trunk/src/waeup/sirp/README.txt @ 5121

The waeup.sirp package
**********************

:Test-Layer: unit

A portal software for student registration.

Prerequisites
=============

Before we can work with the environment, we have to register all the
utilities, adapters, etc. We grok the `waeup` package to do that::

  >>> import grok
  >>> grok.testing.grok('waeup.sirp')

Universities
============

``University`` objects are the base of all functionality provided by
this package.  They contain all facilities of a university.

We can easily create universities::

  >>> from waeup.sirp.app import University
  >>> u = University()
  >>> u
  <waeup.sirp.app.University object at 0x...>

Universities have a name.

  >>> u.name
  u'Sample University'

Universities are basically also containers for faculties, students and
hostels::

  >>> u['faculties']
  <waeup.sirp.university.facultycontainer.FacultyContainer object at 0x...>

  >>> u['students']
  <waeup.sirp.student.studentcontainer.StudentContainer object at 0x...>

  >>> u['hostels']
  <waeup.sirp.hostel.hostelcontainer.HostelContainer object at 0x...>

We can export universities. For this we lookup an appropriate exporter
first::

  >>> from waeup.sirp.interfaces import IWAeUPExporter
  >>> exporter = IWAeUPExporter(u)
  >>> exporter
  <waeup.sirp.utils.importexport.Exporter object at 0x...>

Now we can trigger the export::

  >>> exporter.export()
  <cStringIO.StringO object at 0x...>

We can also get an XML representation as file. If we do not provide a
filepath, we will get an instance of `cStringIO.StringIO`, i.e. a
memory file::

  >>> from waeup.sirp.interfaces import IWAeUPXMLExporter
  >>> exporter = IWAeUPXMLExporter(u)
  >>> f = exporter.export()
  >>> f
  <cStringIO.StringO object at 0x...>

  >>> print f.read()
  <?xml version="1.0" encoding="utf-8" ?>
  <pickle>
    <initialized_object id="...">
  ...
  </pickle>


Faculties
=========

Faculties are containers for departments. They are intended to be
managed by universities.

We can create faculties easily::

  >>> from waeup.sirp.university.faculty import Faculty
  >>> f = Faculty()
  >>> f
  <waeup.sirp.university.faculty.Faculty object at 0x...>

Also faculties want to be named::

  >>> f.title
  u'Unnamed Faculty'

Departments
===========


WAeUP SIRP plugins
==================

waeup.sirp provides an API to 'plugin' components. Things that should
be setup at creation time of a WAeUP SIRP application can indicate
that by providing a utility providing IWAeUPSIRPPlugin.

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

   >>> from waeup.sirp.interfaces import IWAeUPSIRPPluggable
   >>> from zope.component import getAdapters, getUtilitiesFor
   >>> sorted(list(getUtilitiesFor(IWAeUPSIRPPluggable)))
   [(u'accesscodes', <waeup.sirp.accesscodes...AccessCodePlugin ...)]


We can provide a new plugin like this:

   >>> import grok
   >>> from waeup.sirp.interfaces import IWAeUPSIRPPluggable
   >>> class MyPlugin(grok.GlobalUtility):
   ...   grok.implements(IWAeUPSIRPPluggable)
   ...   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 WAeUP SIRP instance, we will get a message:

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

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