[Checkins] SVN: grok/trunk/doc/reference/components.tex Describe
grok.Adapter, grok.MultiAdapter, grok.LocalUtility,
Jan-Wijbrand Kolman
jw at infrae.com
Tue Jun 5 15:43:46 EDT 2007
Log message for revision 76381:
Describe grok.Adapter, grok.MultiAdapter, grok.LocalUtility,
grok.GlobalUtility.
Smaller changes in grok.Site, grok.Container, etc.
Changed:
U grok/trunk/doc/reference/components.tex
-=-
Modified: grok/trunk/doc/reference/components.tex
===================================================================
--- grok/trunk/doc/reference/components.tex 2007-06-05 19:41:14 UTC (rev 76380)
+++ grok/trunk/doc/reference/components.tex 2007-06-05 19:43:45 UTC (rev 76381)
@@ -5,45 +5,80 @@
\section{\class{grok.Adapter}}
- Implementation, configuration, and registration of Zope 3 adapters.
+ Implementation, configuration, and registration of Zope 3 adapters.
- \begin{classdesc*}{grok.Adapter}
- Base class to define an adapter. Adapters are automatically registered
- when a module is grokked.
+ \begin{classdesc*}{grok.Adapter}
+ Base class to define an adapter. Adapters are automatically registered when
+ a module is "grokked".
- \begin{memberdesc}{context}
- The adapted object.
- \end{memberdesc}
+ \begin{memberdesc}{context}
+ The adapted object.
+ \end{memberdesc}
- \begin{bf}Directives:\end{bf}
+ \begin{bf}Directives:\end{bf}
- \begin{itemize}
- \item[\function{grok.context(context_obj)}] required, identifies the required object for the
- adaptation.
+ \begin{itemize}
+ \item[\function{grok.context(context_obj_or_interface)}] Maybe required.
+ Identifies the type of objects or interface for the adaptation.
- \item[\function{grok.implements(interface)}] required, identifies the interface the adapter implements.
+ If Grok can determine a context for adaptation from the module, this
+ directive can be omitted. If the automatically determined context is not
+ correct, or if no context can be derived from the module the directive is
+ required.
- \item[\function{grok.name(name)}] optional, identifies the name used for the adapter
- registration. If ommitted, no name will be used.
- \end{itemize}
- \end{classdesc*}
+ \item[\function{grok.implements(*interfaces)}] Required. Identifies the
+ interface(s) the adapter implements.
- \begin{bf}Example:\end{bf}
+ \item[\function{grok.name(name)}] Optional. Identifies the name used for
+ the adapter registration. If ommitted, no name will be used.
- \begin{verbatim}
-class EuropeanToUS(grok.Adapter):
- """A travel-version of a power adapter that adapts european sockets to
- american sockets.
+ When a name is used for the adapter registration, the adapter can only be
+ retrieved by explicitely using its name.
- """
- grok.implements(IUSPowerSocket)
- grok.context(EuropeanPowerSocket)
- grok.name('travel-adapter') # Optional, can be ommitted
+ \item[\function{grok.provides(name)}] Maybe required. If the adapter
+ implements more than one interface, \function{grok.provides} is required to
+ disambiguate for what interface the adapter will be registered.
+ \end{itemize}
+ \end{classdesc*}
- def power(self):
- return self.context.power
- \end{verbatim}
+ \begin{bf}Example:\end{bf}
+ \begin{verbatim}
+import grok
+from zope import interface
+
+class Cave(grok.Model):
+ pass
+
+class IHome(interface.Interface):
+ pass
+
+class Home(grok.Adapter):
+ grok.implements(IHome)
+
+home = IHome(cave)
+ \end{verbatim}
+
+ \begin{bf}Example 2:\end{bf}
+
+ \begin{verbatim}
+import grok
+from zope import interface
+
+class Cave(grok.Model):
+ pass
+
+class IHome(interface.Interface):
+ pass
+
+class Home(grok.Adapter):
+ grok.implements(IHome)
+ grok.name('home')
+
+from zope.component import getAdapter
+home = getAdapter(cave, IHome, name='home')
+ \end{verbatim}
+
\section{\class{grok.AddForm}}
\section{\class{grok.Annotation}}
@@ -54,12 +89,12 @@
\section{\class{grok.Container}}
- Mixin base class to define a container object. The container supports the
- zope.app.container.interfaces.IContainer interface and is implemented using
- a BTree, providing reasonable performance for large object collections.
+ \begin{classdesc*}{grok.Container}
+ Mixin base class to define a container object. The container implements the
+ zope.app.container.interfaces.IContainer interface using a BTree, providing
+ reasonable performance for large collections of objects.
+ \end{classdesc*}
- Typically used together with \class{grok.Model}.
-
\section{\class{grok.DisplayForm}}
\section{\class{grok.EditForm}}
@@ -68,6 +103,28 @@
\section{\class{grok.GlobalUtility}}
+ \begin{classdesc*}{grok.GlobalUtility}
+ Base class to define a globally registered utility. Global utilities are
+ automatically registered when a module is "grokked".
+
+ \begin{bf}Directives:\end{bf}
+
+ \begin{itemize}
+ \item[\function{grok.implements(*interfaces)}] Required. Identifies the
+ interfaces(s) the utility implements.
+
+ \item[\function{grok.name(name)}] Optional. Identifies the name used for
+ the adapter registration. If ommitted, no name will be used.
+
+ When a name is used for the global utility registration, the global utility
+ can only be retrieved by explicitely using its name.
+
+ \item[\function{grok.provides(name)}] Maybe required. If the global utility
+ implements more than one interface, \function{grok.provides} is required to
+ disambiguate for what interface the global utility will be registered.
+ \end{itemize}
+ \end{classdesc*}
+
\section{\class{grok.Indexes}}
\section{grok.InstanceGrokker}
@@ -76,51 +133,80 @@
\section{\class{grok.LocalUtility}}
-\section{\class{grok.Model}}
+ \begin{classdesc*}{grok.LocalUtility}
+ Base class to define a utility that will be registered local to a
+ \class{grok.Site} or \class{grok.Application} object by using the
+ \function{grok.local_utility} directive.
- Base class to define an application model object.
+ \begin{bf}Directives:\end{bf}
- Model classes support persistence and containment.
+ \begin{itemize}
+ \item[\function{grok.implements(*interfaces)}] Optional. Identifies the
+ interfaces(s) the utility implements.
-\section{grok.ModuleGrokker}
+ \item[\function{grok.name(name)}] Optional. Identifies the name used for
+ the adapter registration. If ommitted, no name will be used.
- Base class to define an application model object.
+ When a name is used for the local utility registration, the local utility
+ can only be retrieved by explicitely using its name.
- Model classes support persistence and containment.
+ \item[\function{grok.provides(name)}] Maybe required. If the local utility
+ implements more than one interface or if the implemented interface cannot
+ be determined, \function{grok.provides} is required to disambiguate for
+ what interface the local utility will be registered.
+ \end{itemize}
+ \end{classdesc*}
+ \begin{seealso}
+ Local utilities need to be registered in the context of \class{grok.Site} or
+ \class{grok.Application} using the \function{grok.local_utility} directive.
+ \end{seealso}
+
+\section{\class{grok.Model}}
+
+ Base class to define an application "content" or model object. Model objects
+ provide persistence and containment.
+
+\section{grok.ModuleGrokker}
+
\section{\class{grok.MultiAdapter}}
- Base class to define a multi-adapter. Multi-adapters are automatically
- registered.
+ \begin{classdesc*}{grok.MultiAdapter}
+ Base class to define a multi adapter. MultiAdapters are automatically
+ registered when a module is "grokked".
- The class-level directive \function{grok.adapts} is used to identify
- the objects that can be adapted.
+ \begin{bf}Directives:\end{bf}
- The class-level directive \function{grok.implements} is used to identify
- the interface(s) this adapter implements.
+ \begin{itemize}
+ \item[\function{grok.adapts(*objects_or_interfaces)}] Required. Identifies
+ the combination of types of objects or interfaces for the adaptation.
- The class-level directive \function{grok.name} is used to register the
- multi-adapter with a name. If ommitted, no name will be used.
+ \item[\function{grok.implements(*interfaces)}] Required. Identifies the
+ interfaces(s) the adapter implements.
+ \item[\function{grok.name(name)}] Optional. Identifies the name used for
+ the adapter registration. If ommitted, no name will be used.
+
+ When a name is used for the adapter registration, the adapter can only
+ be retrieved by explicitely using its name.
+
+ \item[\function{grok.provides(name)}] Maybe required. If the adapter
+ implements more than one interface, \function{grok.provides} is required to
+ disambiguate for what interface the adapter will be registered.
+ \end{itemize}
+ \end{classdesc*}
+
\section{grok.PageTemplate}
\section{grok.PageTemplateFile}
\section{\class{grok.Site}}
+ Base class to define an site object. Site objects provide persistence and
+ containment.
+
\section{\class{grok.Traverser}}
-\section{\class{grok.Utility}}
-
- Base class to define a utility. Utilities are automatically registered.
-
- The class-level directive \function{grok.implements} is used to identify
- the interface this utility implements. Utilities must provide exactly one
- interface.
-
- The class-level directive \function{grok.name} is used to register the
- utility with a name. If ommitted, no name will be used.
-
\section{\class{grok.View}}
\section{\class{grok.XMLRPC}}
More information about the Checkins
mailing list