[Checkins] SVN: grok/trunk/doc/reference/ Restructuring and
reformating of the reference material.
Jan-Wijbrand Kolman
jw at infrae.com
Wed May 30 16:07:07 EDT 2007
Log message for revision 76015:
Restructuring and reformating of the reference material.
Added a functions.tex file for describing the utility functions
that grok provides.
Changed:
U grok/trunk/doc/reference/components.tex
U grok/trunk/doc/reference/decorators.tex
U grok/trunk/doc/reference/directives.tex
U grok/trunk/doc/reference/events.tex
A grok/trunk/doc/reference/functions.tex
U grok/trunk/doc/reference/reference.tex
-=-
Modified: grok/trunk/doc/reference/components.tex
===================================================================
--- grok/trunk/doc/reference/components.tex 2007-05-30 20:03:32 UTC (rev 76014)
+++ grok/trunk/doc/reference/components.tex 2007-05-30 20:07:06 UTC (rev 76015)
@@ -3,25 +3,10 @@
The \module{grok} module defines a set of components that provide basic Zope 3
functionality in a convenient way.
-\section{\class{grok.Model}}
+\section{\class{grok.Adapter}}
- Base class to define an application model object.
-
- Model classes support persistence and containment.
-
-\section{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.
-
- Typically used together with \class{grok.Model}.
-
-\section{grok.Adapter}
-
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.
@@ -49,7 +34,7 @@
class EuropeanToUS(grok.Adapter):
"""A travel-version of a power adapter that adapts european sockets to
american sockets.
-
+
"""
grok.implements(IUSPowerSocket)
grok.context(EuropeanPowerSocket)
@@ -59,8 +44,52 @@
return self.context.power
\end{verbatim}
-\section{grok.MultiAdapter}
+\section{\class{grok.AddForm}}
+\section{\class{grok.Annotation}}
+
+\section{\class{grok.Application}}
+
+\section{grok.ClassGrokker}
+
+\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.
+
+ Typically used together with \class{grok.Model}.
+
+\section{\class{grok.DisplayForm}}
+
+\section{\class{grok.EditForm}}
+
+\section{\class{grok.Form}}
+
+\section{\class{grok.GlobalUtility}}
+
+\section{\class{grok.Indexes}}
+
+\section{grok.InstanceGrokker}
+
+\section{\class{grok.JSON}}
+
+\section{\class{grok.LocalUtility}}
+
+\section{\class{grok.Model}}
+
+ Base class to define an application model object.
+
+ Model classes support persistence and containment.
+
+\section{grok.ModuleGrokker}
+
+ Base class to define an application model object.
+
+ Model classes support persistence and containment.
+
+\section{\class{grok.MultiAdapter}}
+
Base class to define a multi-adapter. Multi-adapters are automatically
registered.
@@ -73,8 +102,16 @@
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}
+\section{grok.PageTemplate}
+\section{grok.PageTemplateFile}
+
+\section{\class{grok.Site}}
+
+\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
@@ -84,10 +121,6 @@
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{\class{grok.View}}
-\section{grok.XMLRPC}
-
-\section{grok.Traverser}
-
-\section{grok.EditForm}
+\section{\class{grok.XMLRPC}}
Modified: grok/trunk/doc/reference/decorators.tex
===================================================================
--- grok/trunk/doc/reference/decorators.tex 2007-05-30 20:03:32 UTC (rev 76014)
+++ grok/trunk/doc/reference/decorators.tex 2007-05-30 20:07:06 UTC (rev 76015)
@@ -6,12 +6,10 @@
\section{\function{grok.subscribe} -- Register a function as a subscriber
for an event}
-
\begin{funcdesc}{subscribe}{*classes_or_interfaces}
Declare that the decorated function subscribes to an event or a
combination of objects and events and register it.
-
Applicable on module-level for functions. Requires at least one class
or interface as argument.
@@ -20,6 +18,4 @@
performs the registration of the component.)
\end{funcdesc}
-
\section{grok.action}
-
Modified: grok/trunk/doc/reference/directives.tex
===================================================================
--- grok/trunk/doc/reference/directives.tex 2007-05-30 20:03:32 UTC (rev 76014)
+++ grok/trunk/doc/reference/directives.tex 2007-05-30 20:07:06 UTC (rev 76015)
@@ -3,60 +3,144 @@
The \module{grok} module defines a set of directives that allow you to
configure and register your components. Most directives assume a default, based
on the environment of a module. (For example, a view will be automatically
-associated with a model if the association can be made unambigously.)
+associated with a model if the association can be made unambigously.)
If no default can be assumed for a value, grok will explicitly tell you what is
missing and how you can provide a default or explicit assignment for the value
in question.
+ \section{\function{grok.AutoFields}}
+
+ \begin{funcdesc}{grok.AutoFields}{*arg}
+ foobar
+ \end{funcdesc}
+
+ \section{\function{grok.adapts}}
+
+ \begin{funcdesc}{grok.adapts}{*interfaces}
+ foobar
+ \end{funcdesc}
+
+ \section{\function{grok.baseclass}}
+
+ \begin{funcdesc}{grok.baseclass}{*interfaces}
+ foobar
+ \end{funcdesc}
+
+ \section{\function{grok.define_permission}}
+
+ \begin{funcdesc}{grok.define_permission}{*arg}
+ foobar
+ \end{funcdesc}
+
+ \section{\function{grok.Fields}}
+
+ \begin{funcdesc}{grok.Fields}{*arg}
+ foobar
+ \end{funcdesc}
+
\section{\function{grok.implements}}
+ \begin{funcdesc}{grok.implements}{*arg}
+ foobar
+ \end{funcdesc}
+
\section{\function{grok.context}}
+ \begin{funcdesc}{grok.context}{*arg}
+ foobar
+ \end{funcdesc}
+
+ \section{\function{grok.global_utility}}
+
+ \begin{funcdesc}{grok.global_utility}{*arg}
+ foobar
+ \end{funcdesc}
+
\section{\function{grok.name}}
- 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.
+ \begin{funcdesc}{grok.name}{*arg}
+ foobar
+ \end{funcdesc}
- \section{\function{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{\function{grok.templatedir}}
+ \section{\function{grok.local_utility}}
+ \begin{funcdesc}{grok.local_utility}{*arg}
+ foobar
+ \end{funcdesc}
+
+ \section{\function{grok.provides}}
+
+ \begin{funcdesc}{grok.provides}{*arg}
+ foobar
+ \end{funcdesc}
+
\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.
+ \begin{funcdesc}{grok.resourcedir}{*arg}
+ foobar
+ \end{funcdesc}
-XXX insert directive description here (first: define the name, second: describe
-the default behaviour if the directive isn't given)
+ Resource directories are used to embed static resources like HTML-,
+ JavaScript-, CSS- and other files in your application.
-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>}.
+ XXX insert directive description here (first: define the name, second:
+ describe the default behaviour if the directive isn't given)
-\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}.
+ 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{notice}A package can never have both a \file{static} directory
- and a Python module with the name \file{static.py} at the same
- time. grok will remind you of this conflict when grokking a package
- by displaying an error message.
+ \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}.
-\end{notice}
+ \begin{notice}
+ A package can never have both a \file{static} directory and a Python
+ module with the name \file{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}
+ \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:
+ 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}
+ \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.
+ The keyword \keyword{static} will be replaced by the reference to
+ the resource directory for the package in which the template was
+ registered.
+ \section{\function{grok.require}}
+
+ \begin{funcdesc}{grok.require}{*arg}
+ foobar
+ \end{funcdesc}
+
+ \section{\function{grok.site}}
+
+ \begin{funcdesc}{grok.site}{*arg}
+ foobar
+ \end{funcdesc}
+
+ \section{\function{grok.template}}
+
+ \begin{funcdesc}{grok.template}{*arg}
+ foobar
+ \end{funcdesc}
+
+ \section{\function{grok.templatedir}}
+
+ \begin{funcdesc}{grok.templatedir}{*arg}
+ foobar
+ \end{funcdesc}
Modified: grok/trunk/doc/reference/events.tex
===================================================================
--- grok/trunk/doc/reference/events.tex 2007-05-30 20:03:32 UTC (rev 76014)
+++ grok/trunk/doc/reference/events.tex 2007-05-30 20:07:06 UTC (rev 76015)
@@ -4,17 +4,30 @@
Those events include object and containment events. All events are available as
interface and implemented class.
- \section{grok.IObjectCreatedEvent}
+ \section{grok.IContainerModifiedEvent}
- \section{grok.IObjectModifiedEvent}
+ \section{grok.IObjectAddedEvent}
\section{grok.IObjectCopiedEvent}
- \section{grok.IObjectAddedEvent}
+ \section{grok.IObjectCreatedEvent}
+ \section{grok.IObjectModifiedEvent}
+
\section{grok.IObjectMovedEvent}
\section{grok.IObjectRemovedEvent}
- \section{grok.IContainerModifiedEvent}
+ \section{grok.ContainerModifiedEvent}
+ \section{grok.ObjectAddedEvent}
+
+ \section{grok.ObjectCopiedEvent}
+
+ \section{grok.ObjectCreatedEvent}
+
+ \section{grok.ObjectModifiedEvent}
+
+ \section{grok.ObjectMovedEvent}
+
+ \section{grok.ObjectRemovedEvent}
Added: grok/trunk/doc/reference/functions.tex
===================================================================
--- grok/trunk/doc/reference/functions.tex (rev 0)
+++ grok/trunk/doc/reference/functions.tex 2007-05-30 20:07:06 UTC (rev 76015)
@@ -0,0 +1,43 @@
+\chapter{Functions}
+
+The \module{grok} module provides access to commonly used functions in the
+Zope Component Architecture.
+
+ \section{\function{grok.getSite}}
+
+ \begin{funcdesc}{grok.getSite}{*args}
+ foobar
+ \end{funcdesc}
+
+ \section{\function{grok.notify}}
+
+ \begin{funcdesc}{grok.notify}{*args}
+ foobar
+ \end{funcdesc}
+
+The \module{grok} module provides a number of convenience functions to aid in
+common tasks.
+
+ \section{\function{grok.url}}
+
+ \begin{funcdesc}{grok.url}{request, object, \optional{, name}}
+ Construct a URL for the given \var{request} and \var{object}.
+
+ \var{name} may be a string that gets appended to the object URL.
+ Commonly used to construct an URL to a particular view on the object.
+
+ This function returns the constructed URL as a string.
+
+ An example, that uses grok.url inside a view class:
+ \begin{verbatim}
+import grok
+
+class SomeView(grok.View):
+
+ def render(self):
+ parent_url = grok.url(
+ self.request, self.context.__parent__, 'index')
+ return '<a href="%s">parent</a>' % parent_url
+ \end{verbatim}
+
+ \end{funcdesc}
\ No newline at end of file
Modified: grok/trunk/doc/reference/reference.tex
===================================================================
--- grok/trunk/doc/reference/reference.tex 2007-05-30 20:03:32 UTC (rev 76014)
+++ grok/trunk/doc/reference/reference.tex 2007-05-30 20:07:06 UTC (rev 76015)
@@ -33,23 +33,25 @@
\maketitle
-``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
+ \begin{quote}
+ ``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{quote}
\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.
+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}
@@ -60,9 +62,10 @@
\include{decorators}
+\include{functions}
+
\include{events}
\include{exceptions}
-
\end{document}
More information about the Checkins
mailing list