[Checkins] SVN: Sandbox/ulif/grok-reference/doc/reference/ Updated
directives reference.
Uli Fouquet
uli at gnufix.de
Sat Aug 25 02:11:06 EDT 2007
Log message for revision 79248:
Updated directives reference.
Changed:
U Sandbox/ulif/grok-reference/doc/reference/directives.tex
U Sandbox/ulif/grok-reference/doc/reference/reference.tex
-=-
Modified: Sandbox/ulif/grok-reference/doc/reference/directives.tex
===================================================================
--- Sandbox/ulif/grok-reference/doc/reference/directives.tex 2007-08-25 06:08:25 UTC (rev 79247)
+++ Sandbox/ulif/grok-reference/doc/reference/directives.tex 2007-08-25 06:11:05 UTC (rev 79248)
@@ -1,38 +1,194 @@
-\chapter{Directives}
+;;\chapter{Directives}
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.)
+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.)
-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.
+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
+ \section{\function{grok.AutoFields} -- deduce schema fields automatically}
+
+ \begin{funcdesc}{grok.AutoFields}{class_or_interface}
+ A class level directive, which can be used inside
+ \class{Form} classes to automatically deduce the form fields
+ from the schema of the context \var{class_or_interface}.
+
+ Different to most other directives,
+ \function{grok.AutoFields} is used more like a function and
+ less like a pure declaration.
+
+ The following example makes use of the
+ \function{grok.AutoFields} directive, in that one field is
+ omitted from the form before rendering:
+
+ \strong{Example:}
+
+ \begin{verbatim}
+import grok
+from zope import interface, schema
+
+class IMammoth(interface.Interface):
+ name = schema.TextLine(title=u"Name")
+ size = schema.TextLine(title=u"Size", default=u"Quite normal")
+
+class Mammoth(grok.Model):
+ interface.implements(IMammoth)
+
+class Edit(grok.EditForm):
+ grok.context(Mammoth)
+
+ form_fields = grok.AutoFields(Mammoth).omit('size')
+ \end{verbatim}
+
+ In this example the \code{size} attribute will not show up
+ in the resulting edit view.
+
+ \begin{seealso}
+ \class{grok.EditForm}, \class{grok.Fields}
+ \end{seealso}
+
\end{funcdesc}
- \section{\function{grok.adapts}}
+ \section{\function{grok.adapts} -- declare that a class adapts
+ certain objects}
- \begin{funcdesc}{grok.adapts}{*interfaces}
- foobar
+ \begin{funcdesc}{grok.adapts}{*classes_or_interfaces}
+ A class-level directive to declare that a class adapts
+ objects of the classes or interfaces given in
+ \var{*classes_or_interfaces}.
+
+ This directive accepts several arguments.
+
+ It works much like the \module{zope.component}s
+ \function{adapts()}, but you do not have to make a ZCML
+ entry to register the adapter.
+
+ \strong{Example:}
+
+ \begin{verbatim}
+import grok
+from zope import interface, schema
+from zope.size.interfaces import ISized
+
+class IMammoth(interface.Interface):
+ name = schema.TextLine(title=u"Name")
+ size = schema.TextLine(title=u"Size", default=u"Quite normal")
+
+class Mammoth(grok.Model):
+ interface.implements(IMammoth)
+
+class MammothSize(object):
+ grok.implements(ISized)
+ grok.adapts(IMammoth)
+
+ def __init__(self, context):
+ self.context = context
+
+ def sizeForSorting(self):
+ return ('byte', 1000)
+
+ def sizeForDisplay(self):
+ return ('1000 bytes')
+ \end{verbatim}
+
+ Having \class{MammothSize} available, you can register it as
+ an adapter, without a single line of ZCML:
+
+ \begin{verbatim}
+>>> manfred = Mammoth()
+>>> from zope.component import provideAdapter
+>>> provideAdapter(MammothSize)
+>>> from zope.size.interfaces import ISized
+>>> size = ISized(manfred)
+>>> size.sizeForDisplay()
+'1000 bytes'
+ \end{verbatim}
+
+ \begin{seealso}
+ \class{grok.implements}
+ \end{seealso}
+
\end{funcdesc}
- \section{\function{grok.baseclass}}
+ \section{\function{grok.baseclass} -- declare a class as base}
- \begin{funcdesc}{grok.baseclass}{*interfaces}
- foobar
+ \begin{funcdesc}{grok.baseclass}{}
+ A class-level directive without argument to mark something
+ as a base class. Base classes are are not grokked.
+
+ Another way to indicate that something is a base class, is
+ by postfixing the classname with \code{'Base'}.
+
+ The baseclass mark is not inherited by subclasses, so those
+ subclasses will be grokked (except they are explicitly
+ declared as baseclasses as well).
+
+ \strong{Example:}
+
+ \begin{verbatim}
+import grok
+
+class ModelBase(grok.Model):
+ pass
+
+class ViewBase(grok.View):
+ def render(self):
+ return "hello world"
+
+class AnotherView(grok.View):
+ grok.baseclass()
+
+ def render(self):
+ return "hello world"
+
+class WorkingView(grok.View):
+ pass
+ \end{verbatim}
+
+ Using this example, only the \class{WorkingView} will serve
+ as a view, while calling the \class{ViewBase} or
+ \class{AnotherView} will lead to a
+ \exception{ComponentLookupError}.
+
+
\end{funcdesc}
- \section{\function{grok.define_permission}}
+ \section{\function{grok.define_permission} -- define a permission}
- \begin{funcdesc}{grok.define_permission}{*arg}
- foobar
+ \begin{funcdesc}{grok.define_permission}{name}
+
+ A module-level directive to define a permission with name
+ \var{name}. Usually permission names are prefixed by a
+ component- or application name and a dot to keep them
+ unique.
+
+ Because in Grok by default everything is accessible by
+ everybody, it is important to define permissions, which
+ restrict access to certain principals or roles.
+
+ \strong{Example:}
+
+ \begin{verbatim}
+import grok
+grok.define_permission('cave.enter')
+ \end{verbatim}
+
+ \begin{seealso}
+ \function{grok.require()}, \class{grok.Permission},
+ \class{grok.Role}
+ \end{seealso}
+
+ \versionchanged[replaced by \class{grok.Permission}]{0.11}
+
\end{funcdesc}
+
+
\section{\function{grok.Fields}}
\begin{funcdesc}{grok.Fields}{*arg}
Modified: Sandbox/ulif/grok-reference/doc/reference/reference.tex
===================================================================
--- Sandbox/ulif/grok-reference/doc/reference/reference.tex 2007-08-25 06:08:25 UTC (rev 79247)
+++ Sandbox/ulif/grok-reference/doc/reference/reference.tex 2007-08-25 06:11:05 UTC (rev 79248)
@@ -15,7 +15,7 @@
% the rest is at your discretion.
\authoraddress{
The grok team\\
- Email: <grok-dev at zope.org>
+ Email: $<$grok-dev at zope.org$>$
}
\date{\today} % update before release!
More information about the Checkins
mailing list