[Checkins] SVN: grokcore.component/trunk/ Improve docs
Philipp von Weitershausen
philikon at philikon.de
Thu May 1 09:45:51 EDT 2008
Log message for revision 86000:
Improve docs
Changed:
U grokcore.component/trunk/CHANGES.txt
U grokcore.component/trunk/README.txt
-=-
Modified: grokcore.component/trunk/CHANGES.txt
===================================================================
--- grokcore.component/trunk/CHANGES.txt 2008-05-01 12:52:41 UTC (rev 85999)
+++ grokcore.component/trunk/CHANGES.txt 2008-05-01 13:45:49 UTC (rev 86000)
@@ -6,6 +6,8 @@
* ...
+* Improved documentation
+
1.0 (2008-05-01)
----------------
Modified: grokcore.component/trunk/README.txt
===================================================================
--- grokcore.component/trunk/README.txt 2008-05-01 12:52:41 UTC (rev 85999)
+++ grokcore.component/trunk/README.txt 2008-05-01 13:45:49 UTC (rev 86000)
@@ -2,9 +2,129 @@
Zope Component Architecture, as well as means for configuring and
registering them directly in Python (without ZCML).
+.. contents::
+How to use ``grokcore.component``
+=================================
+
+In the following we assume you're writing or extending an application
+that does bootstrap configuration using ZCML. There's always a single
+ZCML file that is executed when the application is started, which then
+includes everything else. Let's assume this file is called
+``site.zcml`` (that's what it's called in Zope), so file is what we'll
+be editing.
+
+In order to register the components that you wrote using the base
+classes and directives available from ``grokcore.component``, we use
+the ``<grok:grok />`` ZCML directive. But before we can use it, we
+need to include the necessary meta configuration from
+``grokcore.component``::
+
+ <include package="grokcore.component" file="meta.zcml" />
+
+Put this line next to other meta configuration includes. Now, further
+down the line, we can tell the machinery in ``grokcore.component`` to
+register all components in your package (let's say it's called
+``helloworld``)::
+
+ <grok:grok package="helloworld" />
+
+To sum up, your ``site.zcml`` file should look like something like this::
+
+ <configure
+ xmlns="http://namespaces.zope.org/zope"
+ xmlns:grok="http://namespaces.zope.org/grok">
+
+ <!-- do the meta configuration to make the ZCML directives available -->
+ <include package="zope.foobar" file="meta.zcml" />
+ <include package="zope.frobnaz" file="meta.zcml" />
+ <include package="grokcore.component" file="meta.zcml" />
+
+ <!-- now load the configuration of packages that we depend on -->
+ <include package="zope.barfoo" />
+ <include package="zope.somethingorother" />
+
+ <!-- finally load my components which are based on grokcore.component -->
+ <grok:grok package="helloworld" />
+
+ </configure>
+
+Examples
+========
+
+Here's a simple adapter that may be useful in Zope. It extracts the
+languages that a user prefers from the request::
+
+ import grokcore.component
+ from zope.publisher.interfaces.browser import IBrowserRequest
+ from zope.i18n.interfaces import IUserPreferredLanguages
+
+ class CookieLanguage(grokcore.component.Adapter):
+ """Extract the preferred language from a cookie"""
+ grokcore.component.context(IBrowserRequest)
+ grokcore.component.implements(IUserPreferredLanguages)
+
+ # No need to implement __init__, it's already provided by the base class.
+
+ def getPreferredLanguages(self):
+ # This an adapter for the request, so self.context is the request.
+ request = self.context
+
+ # Extract the preferred language from a cookie:
+ lang = request.cookies.get('language', 'en')
+
+ # According to IUserPreferredLanguages, we must return a list.
+ return [lang]
+
+Here's a simple named utility, again from the Zope world. It's a
+translation domain. In other words, it contains translations of user
+messages and is invoked when the i18n machinery needs to translate
+something::
+
+ import grokcore.component
+ from zope.i18n.interfaces import ITranslationDomain
+
+ class HelloWorldTranslationDomain(grokcore.component.GlobalUtility):
+ grokcore.component.implements(ITranslationDomain)
+ grokcore.component.name('helloworld')
+
+ domain = u'helloworld'
+
+ def translate(self, msgid, mapping=None, context=None,
+ target_language=None, default=None):
+ if target_language is None:
+ preferred = IUserPreferredLanguages(context)
+ target_language = preferred.getPreferredLanguages()[0]
+
+ translations = {'de': u'Hallo Welt',
+ 'nl': u'Hallo Wereld'}
+ return translations.get(target_language, u'Hello World')
+
+Of course, it's silly to implement your own translation domain utility
+if there are already implementations available in ``zope.i18n`` (one
+that reads translations from a GNU gettext message catalog and a
+simple implementation for tests). Let's try to reuse that
+implementation and register an instance::
+
+ import grokcore.component
+ from zope.i18n.interfaces import ITranslationDomain
+ from zope.i18n.simpletranslationdomain import SimpleTranslationDomain
+
+ messages = {('de', u'Hello World'): u'Hallo Welt',
+ ('nl', u'Hello World'): u'Hallo Wereld'}
+ helloworld_domain = SimpleTranslationDomain(u'helloworld', messages)
+
+ grokcore.component.global_utility(helloworld_domain,
+ provides=ITranslationDomain,
+ name='helloworld',
+ direct=True)
+
+
+API
+===
+
Base classes
-============
+------------
``Adapter``
Base class for an adapter that adapts a single object (commonly
@@ -40,11 +160,12 @@
Class-level directives
-======================
+----------------------
``implements(iface1, iface2, ...)``
declares that a class implements the interfaces ``iface1``,
- ``iface2``, etc.
+ ``iface2``, etc. It is identical to
+ ``zope.interface.implements``.
``context(iface_or_class)``
declares the type of object that the adapter (or a similar
@@ -78,7 +199,7 @@
Module-level directives
-=======================
+-----------------------
``global_utility(class, [provides=iface, name=ascii_or_unicode, direct=bool])``
registers an instance of ``class`` (or ``class`` itself, depending
@@ -88,7 +209,7 @@
Function decorators
-===================
+-------------------
``@adapter(iface_or_class1, iface_or_class2, ...)``
registers the function as an adapter for the specific interface.
More information about the Checkins
mailing list