[Checkins] SVN: bluebream/website/docs/v1.0/howto/localsitemanager.rst reviewed
Christophe Combelles
ccomb at free.fr
Tue Jul 27 19:45:34 EDT 2010
Log message for revision 115133:
reviewed
Changed:
U bluebream/website/docs/v1.0/howto/localsitemanager.rst
-=-
Modified: bluebream/website/docs/v1.0/howto/localsitemanager.rst
===================================================================
--- bluebream/website/docs/v1.0/howto/localsitemanager.rst 2010-07-27 23:15:54 UTC (rev 115132)
+++ bluebream/website/docs/v1.0/howto/localsitemanager.rst 2010-07-27 23:45:34 UTC (rev 115133)
@@ -1,15 +1,20 @@
-Creating Local Site Manager
-===========================
+Creating a Local Site Manager
+=============================
+Bluebream uses the Zope Component Architecture, which provides you with
+registries of components, such as adapters or utilities. You can create two
+types of registries: global and local. The global registry is unique, created
+automatically, and populated with all the registrations done in the ZCML files.
+The local registries are persistent and typically live in the ZODB database, in
+what is called a `local site manager`. Local registries allow you to override or
+create component registrations in the object hierarchy, in a contextuel manner.
+
Quick start
-----------
-This document explains creating of a local site manager. Local site
-manager provides a persistent component registry where local
-components like local utilities can be registered. To try the
-examples given here, you can create a project as explained in the
-:ref:`started-getting` document. Here is the commands to create a
-sample project.::
+This document explains how to create a local site manager. To try the examples
+given here, you can create a project as explained in the :ref:`started-getting`
+document. Here are the commands to create a sample project.::
$ easy_install bluebream
$ paster create -t bluebream sampleproject python_package=mycompany.main
@@ -25,7 +30,7 @@
app.setSiteManager(LocalSiteManager(app))
-Be sure to add the following import to the top of the file::
+Be sure to add the following import at the top of the file::
from zope.site import LocalSiteManager
@@ -35,20 +40,20 @@
app.setSiteManager(LocalSiteManager(app))
self.request.response.redirect(name)
-That's it. Now, each added using this form will be a "site". But what
-does it mean?
+That's it. Now, each application added using this form will be a "site". But
+what does it mean?
Site Managers
-------------
-*Site* is persistent object used to provide custom component setups
-for a part of your application or whole web site. For this, it
-contains *Site Manager*, which is:
+A *Site* is a persistent object used to provide custom component setups
+for a part of your application or the whole web site. For this purpose, it
+contains a *Site Manager*, which is:
-1. container for local components
+1. a container for local components
2. and it has local registry for those components.
-Imagine hierarhy in ZODB::
+Imagine this hierarchy in the ZODB::
root---------FIRST
|
@@ -61,8 +66,8 @@
``++etc++site`` means `Local Site Manager` itself. Thus, ``root`` and
``app`` are *Sites*. Let's make ``RootCookieManager`` and
``AppCookieManager`` to be utilities registered in their `Site
-Managers` as utilities provide interface
-``zope.session.interfaces.IClientIdManager`` and with empty name.
+Managers` as utilities providing interface
+``zope.session.interfaces.IClientIdManager`` and with an empty name.
Let's query unnamed utility provided interface
``zope.session.interfaces.IClientIdManager``:
@@ -77,16 +82,16 @@
site manager), which you have use for registering non-persistent
components. We will not explain it in this document.
-How does it usually look like ?
--------------------------------
+How does it usually look like?
+------------------------------
-When do you need local utilities? Here are reasons to create local
+When do you need local utilities? Here are some reasons to create a local
utility:
-- you need persistent object and you need to edit its attributes or
+- you need a persistent object and you need to edit its attributes or
it should contain other objects
-- you require this object in a single copy (i.e. `singleton
+- you require this object to exist in a single copy (i.e. `singleton
<http://en.wikipedia.org/wiki/Singleton_pattern>`_)
- you need to have the ability to fetch this object from everywhere
@@ -95,35 +100,37 @@
Which local utilities are commonly used? List of interfaces they
provide:
-- ``zope.intid.interfaces.IIntIds`` this utility assigns unique ids
- to objects.
+- ``zope.intid.interfaces.IIntIds`` this utility assigns unique identifiers to
+ objects.
- ``zope.catalog.interfaces.ICatalog`` contains and manage search
indexes.
-- ``zope.authentication.interfaces.IAuthentication`` provide support
+- ``zope.authentication.interfaces.IAuthentication`` provides support
to establish principals for requests.
Use event handler
-----------------
-In the add form above you set Site Manager directly in the form. But
-let's separate this logic from view. Events system is another edge
-of polyhedron of component architecture used in BlueBream. Event
+In the add form above, you set the Site Manager directly in the form. But
+let's separate this logic from the view. Events system is another edge
+of polyhedron of the Component Architecture used in BlueBream. Event
caller and event handler do not know about each other and even do not
require each other.
Event caller
- We needn't write caller for this event, because it is done by
- container itself. When you add object into container, it calls
- event which provides interface
+
+ We don't need to write a caller for this event, because it is done by
+ the container itself. When you add an object into the container, it calls
+ an event which provides interface
``zope.lifecycleevent.interfaces.IObjectAddedEvent``.
Event handlers
+
Handlers in BlueBream (generally, in ZTK) are subscription adapter
factories that don't produce anything. This implies a lot of
- interesting possibilities, but will not consider them in this
- document. Just write it - it is simple function (`handler.py`)::
+ interesting possibilities, but we won't consider them in this
+ document. Just write it - it is a simple function (`handler.py`)::
from zope.site import LocalSiteManager
@@ -131,7 +138,7 @@
site.setSiteManager(LocalSiteManager(site, False))
sm = site.getSiteManager()
- and register this function as handler for events which provide
+ and register this function as a handler for events which provide
interface ``IObjectAddedEvent`` (`configure.zcml`)::
<subscriber
@@ -143,17 +150,17 @@
ISite interface
---------------
-We showed above: "*Site* is a persistent object used..." But in
-terminology of component architecture we do not need to speak about
-objects, i.e. about implementations. It is enough to speak about
+As we showed above, "A *Site* is a persistent object used..." But in
+the terminology of the component architecture we don't need to speak about
+objects, i.e. about implementations. It is sufficient to speak about
interfaces which these objects do provide.
-In this "language" *Site* is object which provides interface
+In this "language", *Site* is an object which provides interface
``zope.component.interfaces.ISite``. And it happens automatically
-after we set Local Site Manager. But to do this, we need object
+after we set Local Site Manager. But to do this, we need an object
which implements ``zope.component.interfaces.IPossibleSite``. That
is why you have used ``zope.site.folder.Folder`` container. Thus,
-there are convertation::
+there is a conversion::
IPossibleSite ---> ISite
@@ -168,13 +175,14 @@
3. Local component registry named usually `Local Site Manager`
(technically, it contains the registry).
-4. It contained in object which provide
+4. It is contained in objects which provide
``zope.component.interfaces.ISite`` interface.
-5. To make this, you need to use object, which provide interface
+5. To make this, you need to use an object, which provides interface
``zope.component.interfaces.IPossibleSite``, and call its method
``setSiteManager``.
-6. Good place to do this - `Event Handler` which is subscribed to 2
+6. A good place to do this - `Event Handler` which is subscribed to 2
interfaces: your custom site's interface and
``zope.lifecycleevent.interfaces.IObjectAddedEvent``.
+
More information about the checkins
mailing list