[Checkins] SVN: grok/trunk/doc/reference/ - restructuring,
finally getting somewhere
Christian Theune
ct at gocept.com
Mon Dec 11 11:40:46 EST 2006
Log message for revision 71523:
- restructuring, finally getting somewhere
Changed:
_U grok/trunk/doc/reference/
U grok/trunk/doc/reference/components.tex
U grok/trunk/doc/reference/core.tex
U grok/trunk/doc/reference/decorators.tex
U grok/trunk/doc/reference/directives.tex
U grok/trunk/doc/reference/reference.tex
-=-
Property changes on: grok/trunk/doc/reference
___________________________________________________________________
Name: svn:ignore
- reference.pdf
reference
.aux
+ reference.pdf
reference
*.aux
*.how
Modified: grok/trunk/doc/reference/components.tex
===================================================================
--- grok/trunk/doc/reference/components.tex 2006-12-11 16:39:55 UTC (rev 71522)
+++ grok/trunk/doc/reference/components.tex 2006-12-11 16:40:46 UTC (rev 71523)
@@ -3,20 +3,91 @@
The \module{grok} module defines a set of components that provide basic Zope 3
functionality in a convenient way.
- \section{grok.Model}
+\section{\class{grok.Model}}
- \section{grok.Container}
+ Base class to define an application model object.
- \section{grok.Adapter}
+ Model classes support persistence and containment.
- \section{grok.MultiAdapter}
+\section{grok.Container}
- \section{grok.Utility}
+ 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.
- \section{grok.View}
+ Typically used together with \class{grok.Model}.
- \section{grok.XMLRPC}
+\section{grok.Adapter}
- \section{grok.Traverser}
+ Implementation, configuration, and registration of Zope 3 adapters.
- \section{grok.EditForm}
+
+ \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{bf}Directives:\end{bf}
+
+ \begin{itemize}
+ \item[\function{grok.context(context_obj)}] required, identifies the required object for the
+ adaptation.
+
+ \item[\function{grok.implements(interface)}] required, identifies the interface the adapter implements.
+
+ \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*}
+
+ \begin{bf}Example:\end{bf}
+
+ \begin{verbatim}
+class EuropeanToUS(grok.Adapter):
+ """A travel-version of a power adapter that adapts european sockets to
+ american sockets.
+
+ """
+ grok.implements(IUSPowerSocket)
+ grok.context(EuropeanPowerSocket)
+ grok.name('travel-adapter') # Optional, can be ommitted
+
+ def power(self):
+ return self.context.power
+ \end{verbatim}
+
+\section{grok.MultiAdapter}
+
+ Base class to define a multi-adapter. Multi-adapters are automatically
+ registered.
+
+ The class-level directive \function{grok.adapts} is used to identify
+ the objects that can be adapted.
+
+ The class-level directive \function{grok.implements} is used to identify
+ the interface(s) this adapter implements.
+
+ The class-level directive \function{grok.name} is used to register the
+ multi-adapter with a name. If ommitted, no name will be used.
+
+\section{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{grok.View}
+
+\section{grok.XMLRPC}
+
+\section{grok.Traverser}
+
+\section{grok.EditForm}
Modified: grok/trunk/doc/reference/core.tex
===================================================================
--- grok/trunk/doc/reference/core.tex 2006-12-11 16:39:55 UTC (rev 71522)
+++ grok/trunk/doc/reference/core.tex 2006-12-11 16:40:46 UTC (rev 71523)
@@ -2,5 +2,48 @@
The \module{grok} module defines a few functions to interact with grok itself.
- \section{grok.grok}
+\section{\function{grok.grok} -- Grok a package or module}
+
+ \begin{funcdesc}{grok}{dotted_name}
+
+ Grokking a package or module activates the contained components (like
+ models, views, adapters, templates, etc.) and registers them with Zope 3's
+ component architecture.
+
+ The \var{dotted_name} must specify either a Python module or package
+ that is available from the current PYTHONPATH.
+
+ Grokking a module:
+
+ \begin{enumerate}
+
+ \item Scan the module for known components: models, adapters,
+ utilities, views, traversers, templates and subscribers.
+
+ \item Check whether a directory with file system templates exists
+ (``<modulename>_templates''). If it exists, load the file system
+ templates into the template registry for this module.
+
+ \item Determine the module context.
+
+ \item Register all components with the Zope 3 component architecture.
+
+ \item Initialize schemata for registered models
+
+ \end{enumerate}
+
+ Grokking a package:
+
+ \begin{enumerate}
+ \item Grok the package as a module.
+
+ \item Check for a static resource directory (``static'') and register
+ it if it exists.
+
+ \item Recursively grok all sub-modules and sub-packages.
+
+ \end{enumerate}
+
+ \end{funcdesc}
+
Modified: grok/trunk/doc/reference/decorators.tex
===================================================================
--- grok/trunk/doc/reference/decorators.tex 2006-12-11 16:39:55 UTC (rev 71522)
+++ grok/trunk/doc/reference/decorators.tex 2006-12-11 16:40:46 UTC (rev 71523)
@@ -10,12 +10,14 @@
\begin{funcdesc}{subscribe}{*classes_or_interfaces}
Declare that the decorated function subscribes to an event or a
- combination of objects and events. (Similar to Zope 3's
- \function{subscriber} decorator.)
+ combination of objects and events and register it.
+
Applicable on module-level for functions. Requires at least one class
or interface as argument.
+ (Similar to Zope 3's \function{subscriber} decorator, but automatically
+ performs the registration of the component.)
\end{funcdesc}
Modified: grok/trunk/doc/reference/directives.tex
===================================================================
--- grok/trunk/doc/reference/directives.tex 2006-12-11 16:39:55 UTC (rev 71522)
+++ grok/trunk/doc/reference/directives.tex 2006-12-11 16:40:46 UTC (rev 71523)
@@ -9,15 +9,53 @@
missing and how you can provide a default or explicit assignment for the value
in question.
- \section{grok.implements}
+ \section{\function{grok.implements}}
- \section{grok.context}
+ \section{\function{grok.context}}
- \section{grok.name}
+ \section{\function{grok.name}}
- \section{grok.template}
+ Used to associate a component with a name. Typically this directive is
+ optional. The default behaviour when no name is given depends on the
+ component.
- \section{grok.templatedir}
+ \section{\function{grok.template}}
- \section{grok.templatedir}
+ \section{\function{grok.templatedir}}
+ \section{\function{grok.resourcedir --- XXX Not implemented yet}}
+
+Resource directories are used to embed static resources like HTML-,
+JavaScript-, CSS- and other files in your application.
+
+XXX insert directive description here (first: define the name, second: describe
+the default behaviour if the directive isn't given)
+
+A resource directory is created when a package contains a directory with the
+name ``\file{static}''. All files from this directory become accessible from a
+browser under the URL
+\file{http://<servername>/++resource++<packagename>/<filename>}.
+
+\begin{bf}Example:\end{bf} The package \module{a.b.c} is grokked and contains a
+directory \file{static} which contains the file \file{example.css}. The
+stylesheet will be available via
+\file{http://<servername>/++resource++a.b.c/example.css}.
+
+\begin{notice}A package can never have both a ``static'' directory and a Python module
+with the name ``static.py'' at the same time. grok will remind you of this
+conflict when grokking a package by displaying an error message.
+
+\end{notice}
+
+\subsection{Linking to resources from templates}
+
+ grok provides a convenient way to calculate the URLs to static resource
+ using the keyword \keyword{static} in page templates:
+
+ \begin{verbatim}
+ <link rel="stylesheet" tal:attributes="href static/example.css" type="text/css">
+ \end{verbatim}
+
+ The keyword \keyword{static} will be replaced by the reference to the
+ resource directory for the package in which the template was registered.
+
Modified: grok/trunk/doc/reference/reference.tex
===================================================================
--- grok/trunk/doc/reference/reference.tex 2006-12-11 16:39:55 UTC (rev 71522)
+++ grok/trunk/doc/reference/reference.tex 2006-12-11 16:40:46 UTC (rev 71523)
@@ -33,45 +33,23 @@
\maketitle
-% This makes the contents more accessible from the front page of the HTML.
-\ifhtml
-\chapter*{Front matter\label{front}}
-\fi
-
-\copyright 2006 gocept gmbh \& co. kg, Martijn Faassen and Philipp von
-Weitershausen
-
-Licensed under the Zope Public License, Version 2.1 (the ``License''); you may
-not use this file except in compliance with the License. You may obtain a copy
-of the License at \url{http://www.zope.org/Resources/ZPL}.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ``AS IS'' AND ANY EXPRESSED
-OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
-MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
-EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY DIRECT, INDIRECT,
-INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
-LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
-PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
-LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
-OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
-ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-
-\begin{abstract}
-
-\noindent
-
-Grok: now even cavemen can use Zope 3!
-
-\begin{notice}
``Grok means to understand so thoroughly that the observer becomes a part of the
observed --- merge, blend, intermarry, lose identity in group experience.
It means almost everything that we mean by religion, philosophy, and
science --- it means as little to us (because we are from Earth) as color
means to a blind man.'' -- Robert A. Heinlein, Stranger in a Strange Land
-\end{notice}
+\begin{abstract}
+This is the grok reference documentation. It is organized by the Python
+artefacts that implement the concepts.
+
+Grok makes Zope 3 concepts more accessible for application developers. This
+reference is
+not intended as introductory material for those concepts. Please refer to the
+original Zope 3 documentation and the grok tutorial for introductory material.
\end{abstract}
+
\tableofcontents
\include{core}
@@ -86,4 +64,5 @@
\include{exceptions}
+
\end{document}
More information about the Checkins
mailing list