[Checkins] SVN: grok/trunk/doc/reference/ Put in the changes from
the neanderthal-reference-documentation branch.
Jan-Wijbrand Kolman
janwijbrand at gmail.com
Fri Oct 5 10:46:05 EDT 2007
Log message for revision 80654:
Put in the changes from the neanderthal-reference-documentation branch.
Changed:
U grok/trunk/doc/reference/components.rst
U grok/trunk/doc/reference/decorators.rst
U grok/trunk/doc/reference/directives.rst
U grok/trunk/doc/reference/functions.rst
-=-
Modified: grok/trunk/doc/reference/components.rst
===================================================================
--- grok/trunk/doc/reference/components.rst 2007-10-05 14:34:02 UTC (rev 80653)
+++ grok/trunk/doc/reference/components.rst 2007-10-05 14:46:05 UTC (rev 80654)
@@ -3,22 +3,46 @@
Components
**********
+.. Here we documented the component base classes. For the directive possible
+ for each component we document only the specific within its context. We then
+ refer to the directives documented in the directives.rst file.
+
The :mod:`grok` module defines a set of components that provide basic Zope 3
-functionality in a convenient way.
+functionality in a convenient way. Grok applications are built by subclassing
+these components.
+Core components
+~~~~~~~~~~~~~~~
+:class:`grok.Model`
+===================
+
+Base class to define an application "content" or model object. Model objects
+provide persistence and containment.
+
+:class:`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.
+
+:class:`grok.Application`
+=========================
+
+Adapters
+~~~~~~~~
+
:class:`grok.Adapter`
=====================
Implementation, configuration, and registration of Zope 3 adapters.
-
.. class:: grok.Adapter
Base class to define an adapter. Adapters are automatically registered when a
module is "grokked".
-
.. attribute:: grok.Adapter.context
The adapted object.
@@ -28,13 +52,17 @@
:func:`grok.context(context_obj_or_interface)`
Maybe required. Identifies the type of objects or interface for the adaptation.
- 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.
+ .. seealso::
+ :function:`grok.context`
+
:func:`grok.implements(\*interfaces)`
Required. Identifies the interface(s) the adapter implements.
+ .. seealso::
+
+ :function:`grok.implements`
+
:func:`grok.name(name)`
Optional. Identifies the name used for the adapter registration. If ommitted, no
name will be used.
@@ -42,13 +70,19 @@
When a name is used for the adapter registration, the adapter can only be
retrieved by explicitely using its name.
+ .. seealso::
+
+ :function:`grok.name`
+
:func:`grok.provides(name)`
- Maybe required. If the adapter implements more than one interface,
- :func:`grok.provides` is required to disambiguate for what interface the adapter
- will be registered.
+ Maybe required.
-**Example:** ::
+ .. seealso::
+ :function:`grok.provides`
+
+**Example 1:** ::
+
import grok
from zope import interface
@@ -63,7 +97,7 @@
home = IHome(cave)
-**Example 2:** ::
+**Example 2: Register and retrieve the adapter under a specific name** ::
import grok
from zope import interface
@@ -81,50 +115,68 @@
from zope.component import getAdapter
home = getAdapter(cave, IHome, name='home')
+:class:`grok.MultiAdapter`
+==========================
-:class:`grok.AddForm`
-=====================
+.. class:: grok.MultiAdapter
+ Base class to define a multi adapter. MultiAdapters are automatically
+ registered when a module is "grokked".
-:class:`grok.Annotation`
-========================
+ **Directives:**
+ :func:`grok.adapts(\*objects_or_interfaces)`
+ Required. Identifies the combination of types of objects or interfaces
+ for the adaptation.
-:class:`grok.Application`
-=========================
+ :func:`grok.implements(\*interfaces)`
+ Required. Identifies the interfaces(s) the adapter implements.
+ :func:`grok.name(name)`
+ Optional. Identifies the name used for the adapter registration. If
+ ommitted, no name will be used.
-grok.ClassGrokker
-=================
+ When a name is used for the adapter registration, the adapter can only be
+ retrieved by explicitely using its name.
+ :func:`grok.provides(name)`
+ Maybe required. If the adapter implements more than one interface,
+ :func:`grok.provides` is required to disambiguate for what interface the
+ adapter will be registered.
-:class:`grok.Container`
-=======================
+**Example:** ::
+ import grok
+ from zope import interface
-.. class:: grok.Container
+ class Fireplace(grok.Model):
+ pass
- 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.
+ class Cave(grok.Model):
+ pass
+ class IHome(interface.Interface):
+ pass
-:class:`grok.DisplayForm`
-=========================
+ class Home(grok.MultiAdapter):
+ grok.adapts(Cave, Fireplace)
+ grok.implements(IHome)
+ def __init__(self, cave, fireplace):
+ self.cave = cave
+ self.fireplace = fireplace
-:class:`grok.EditForm`
-======================
+ home = IHome(cave, fireplace)
+:class:`grok.Annotation`
+========================
-:class:`grok.Form`
-==================
+Utilities
+~~~~~~~~~
-
:class:`grok.GlobalUtility`
===========================
-
.. class:: grok.GlobalUtility
Base class to define a globally registered utility. Global utilities are
@@ -136,34 +188,20 @@
Required. Identifies the interfaces(s) the utility implements.
:func:`grok.name(name)`
- Optional. Identifies the name used for the adapter registration. If ommitted, no
- name will be used.
+ 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.
+ When a name is used for the global utility registration, the global
+ utility can only be retrieved by explicitely using its name.
:func:`grok.provides(name)`
Maybe required. If the global utility implements more than one interface,
- :func:`grok.provides` is required to disambiguate for what interface the global
- utility will be registered.
+ :func:`grok.provides` is required to disambiguate for what interface the
+ global utility will be registered.
-
-:class:`grok.Indexes`
-=====================
-
-
-grok.InstanceGrokker
-====================
-
-
-:class:`grok.JSON`
-==================
-
-
:class:`grok.LocalUtility`
==========================
-
.. class:: grok.LocalUtility
Base class to define a utility that will be registered local to a
@@ -176,114 +214,103 @@
Optional. Identifies the interfaces(s) the utility implements.
:func:`grok.name(name)`
- Optional. Identifies the name used for the adapter registration. If ommitted, no
- name will be used.
+ Optional. Identifies the name used for the adapter registration. If
+ ommitted, no name will be used.
- When a name is used for the local utility registration, the local utility can
- only be retrieved by explicitely using its name.
+ When a name is used for the local utility registration, the local utility
+ can only be retrieved by explicitely using its name.
:func:`grok.provides(name)`
- Maybe required. If the local utility implements more than one interface or if
- the implemented interface cannot be determined, :func:`grok.provides` is
- required to disambiguate for what interface the local utility will be
- registered.
+ Maybe required. If the local utility implements more than one interface
+ or if the implemented interface cannot be determined,
+ :func:`grok.provides` is required to disambiguate for what interface the
+ local utility will be registered.
+ .. seealso::
-.. seealso::
+ Local utilities need to be registered in the context of :class:`grok.Site`
+ or :class:`grok.Application` using the :func:`grok.local_utility` directive.
- Local utilities need to be registered in the context of :class:`grok.Site` or
- :class:`grok.Application` using the :func:`grok.local_utility` directive.
+:class:`grok.Site`
+==================
+Views
+~~~~~
-:class:`grok.Model`
-===================
+:class:`grok.View`
+==================
-Base class to define an application "content" or model object. Model objects
-provide persistence and containment.
+:class:`grok.JSON
+==================
+:class:`grok.XMLRPC`
+====================
-grok.ModuleGrokker
-==================
+:class:`grok.Traverser`
+=======================
-
-:class:`grok.MultiAdapter`
+:class:`grok.PageTemplate`
==========================
+:class:`grok.PageTemplateFile`
+==============================
-.. class:: grok.MultiAdapter
+Forms
+~~~~~
- Base class to define a multi adapter. MultiAdapters are automatically registered
- when a module is "grokked".
+:class:`grok.Form`
+==================
- **Directives:**
+.. Do not forget about the form_fields class attribute!
- :func:`grok.adapts(\*objects_or_interfaces)`
- Required. Identifies the combination of types of objects or interfaces for the
- adaptation.
+:class:`grok.AddForm`
+=====================
- :func:`grok.implements(\*interfaces)`
- Required. Identifies the interfaces(s) the adapter implements.
+:class:`grok.EditForm`
+======================
- :func:`grok.name(name)`
- Optional. Identifies the name used for the adapter registration. If ommitted, no
- name will be used.
+:class:`grok.DisplayForm`
+=========================
- When a name is used for the adapter registration, the adapter can only be
- retrieved by explicitely using its name.
+Security
+~~~~~~~~
- :func:`grok.provides(name)`
- Maybe required. If the adapter implements more than one interface,
- :func:`grok.provides` is required to disambiguate for what interface the adapter
- will be registered.
+:class:`Permission`
+===================
-**Example:** ::
+:func:`grok.define_permission` -- define a permission
+=====================================================
- import grok
- from zope import interface
+.. function:: grok.define_permission(name)
- class Fireplace(grok.Model):
- pass
+ A module-level directive to define a permission with name
+ `name`. Usually permission names are prefixed by a component- or
+ application name and a dot to keep them unique.
- class Cave(grok.Model):
- pass
+ Because in Grok by default everything is accessible by everybody,
+ it is important to define permissions, which restrict access to
+ certain principals or roles.
- class IHome(interface.Interface):
- pass
+ **Example:** ::
- class Home(grok.MultiAdapter):
- grok.adapts(Cave, Fireplace)
- grok.implements(IHome)
+ import grok
+ grok.define_permission('cave.enter')
- def __init__(self, cave, fireplace):
- self.cave = cave
- self.fireplace = fireplace
- home = IHome(cave, fireplace)
+ .. seealso::
+ :func:`grok.require`, :class:`grok.Permission`, :class:`grok.Role`
-grok.PageTemplate
-=================
+ .. versionchanged:: 0.11
+ replaced by :class:`grok.Permission`.
+:class:`Role`
+=============
-grok.PageTemplateFile
-=====================
+Uncategorized
+~~~~~~~~~~~~~
+.. The weird classes we couldn' categorize yet
-:class:`grok.Site`
-==================
-
-Base class to define an site object. Site objects provide persistence and
-containment.
-
-
-:class:`grok.Traverser`
-=======================
-
-
-:class:`grok.View`
-==================
-
-
-:class:`grok.XMLRPC`
-====================
-
+:class:`grok.Indexes`
+=====================
Modified: grok/trunk/doc/reference/decorators.rst
===================================================================
--- grok/trunk/doc/reference/decorators.rst 2007-10-05 14:34:02 UTC (rev 80653)
+++ grok/trunk/doc/reference/decorators.rst 2007-10-05 14:46:05 UTC (rev 80654)
@@ -13,16 +13,63 @@
.. function:: subscribe(*classes_or_interfaces)
- Declare that the decorated function subscribes to an event or a combination of
- objects and events and register it.
+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.
+Applicable on module-level for functions. Requires at least one class or
+interface as argument.
- (Similar to Zope 3's :func:`subscriber` decorator, but automatically performs
- the registration of the component.)
+(Similar to Zope 3's :func:`subscriber` decorator, but automatically performs
+the registration of the component.)
-grok.action
-===========
+:func:`grok.action` -- Declare a form submit handler
+=====================================================
+
+:func:`grok.require` -- Protect a method with a permission
+===========================================================
+
+:func:`grok.adapter/grok.implementer` -- Declare an adapter factory
+====================================================================
+
+.. XXX these two decorators are always used together, but are named separately because they are separate in the Zope 3 API. Should grok implement this as one decorator with two arguments?
+
+These decorators are always used in tandem to declare an adapter factory.
+
+.. function:: grok.adapter(*interfaces)
+
+`*interfaces` -- the interfaces *adapted* by the object created by this factory.
+
+.. function:: grok.implementer(interface)
+
+`interface` -- the interface *provided* by the object created by this factory.
+
+
+**Example 1:** ::
+
+ @grok.adapter(ICave)
+ @grok.implementer(IHome)
+ def home_for_cave(cave):
+ return Home()
+
+**Example 2: adapt a regular class instead of an interface ** ::
+
+ @grok.adapter(Cave)
+ @grok.implementer(IHome)
+ def home_for_cave(cave):
+ return Home()
+
+**Example 3: declare a multi-adapter factory ** ::
+
+ @grok.adapter(ICave,IFire)
+ @grok.implementer(ICozy)
+ def cozy_dwelling(cave, fire):
+ return Dwelling()
+
+
+
+
+
+
+
Modified: grok/trunk/doc/reference/directives.rst
===================================================================
--- grok/trunk/doc/reference/directives.rst 2007-10-05 14:34:02 UTC (rev 80653)
+++ grok/trunk/doc/reference/directives.rst 2007-10-05 14:46:05 UTC (rev 80654)
@@ -3,6 +3,11 @@
Directives
**********
+.. Here we document the generic behaviour of the module level and class level
+ directives. The context sensitive behaviour is described in the individual
+ component documentation. We do use specific example to illustrate the use
+ of the directives.
+
The :mod:`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
@@ -12,555 +17,467 @@
missing and how you can provide a default or explicit assignment for the value
in question.
+Core directives
+~~~~~~~~~~~~~~~
-:func:`grok.AutoFields` -- Deduce schema fields automatically
-=============================================================
+:func:`grok.context` -- Declare the context for views, adapters, etc.
+=====================================================================
-.. function:: grok.AutoFields(class_or_interface)
+.. function:: grok.context(*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 `class_or_interface`.
+A class or module level directive to indicate the context for something
+(class or module) in the same scope. When used on module level, it will set
+the context for all views, adapters, etc. in that module. When used on class
+level, it will set the context for that particular class.
- Different to most other directives, :func:`grok.AutoFields` is used
- more like a function and less like a pure declaration.
+With Grok contexts are set automatically for some objects, if they are
+unambigous. For example a :class:`grok.View` will get the only
+:class:`grok.Application` or :class:`grok.Model` class as context, iff there
+exists exactly one in the same module. If there are more possible contexts
+or you want to set a type (class/interface) from another module as context,
+than the one choosen by default, then you have to call :func:`grok.context`
+explicitly.
- The following example makes use of the :func:`grok.AutoFields`
- directive, in that one field is omitted from the form before
- rendering:
+**Example:**
-**Example:** ::
+Here the :func:`grok.context` directive indicates, that
+:class:`Mammoth` instances will be the context of :class:`Index`
+views (and not instances of :class:`Cave`) ::
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)
+ pass
- class Edit(grok.EditForm):
+ class Cave(grok.Model):
+ pass
+
+ class Index(grok.View):
grok.context(Mammoth)
- form_fields = grok.AutoFields(Mammoth).omit('size')
-
-In this example the ``size`` attribute will not show up in the
-resulting edit view.
-
-
.. seealso::
- :class:`grok.EditForm`, :func:`grok.Fields`
+ :class:`grok.View`, :class:`grok.Adapter`, :class:`grok.MultiAdapter`
+:func:`grok.name` -- associate a component with a name
+======================================================
-:func:`grok.adapts` -- Declare that a class adapts certain objects
-==================================================================
+.. function:: grok.name(name)
+A class level directive used to associate a component with a single name
+`name`. Typically this directive is optional. The default behaviour when no
+name is given depends on the component. The same applies to the semantics of
+this directive: for what exactly a name is set when using this directive,
+depends on the component.
-.. function:: grok.adapts(*classes_or_interfaces)
+**Example:** ::
- A class-level directive to declare that a class adapts objects of
- the classes or interfaces given in `\*classes_or_interfaces`.
+ import grok
- This directive accepts several arguments.
+ class Mammoth(grok.Model):
+ pass
- It works much like the :mod:`zope.component`\ s :func:`adapts()`,
- but you do not have to make a ZCML entry to register the adapter.
+ # a common use case is to have a URL for a view named differently than
+ # the name of the view class itself.
+ class SomeView(grok.View):
+ grok.name('index')
- **Example:** ::
- import grok
- from zope import interface, schema
- from zope.size.interfaces import ISized
+.. seealso::
- class IMammoth(interface.Interface):
- name = schema.TextLine(title=u"Name")
- size = schema.TextLine(title=u"Size", default=u"Quite normal")
+ :class:`grok.Adapter`, :class:`grok.Annotation`,
+ :class:`grok.GlobalUtility`, :class:`grok.Indexes`,
+ :class:`grok.MultiAdapter`, :class:`grok.Role`,
+ :class:`grok.View`
- class Mammoth(grok.Model):
- interface.implements(IMammoth)
+:func:`grok.title`
+========================
- class MammothSize(object):
- grok.implements(ISized)
- grok.adapts(IMammoth)
+.. function:: grok.title(*arg)
- def __init__(self, context):
- self.context = context
+ foobar
- def sizeForSorting(self):
- return ('byte', 1000)
+:func:`grok.implements` -- indicate, that a class implements an interface
+=========================================================================
- def sizeForDisplay(self):
- return ('1000 bytes')
+.. function:: grok.implements(*interfaces)
- Having :class:`MammothSize` available, you can register it as an adapter,
- without a single line of ZCML::
+A class level directive to declare one or more `interfaces`, as implementers
+of the surrounding class. This directive allows several parameters.
- >>> manfred = Mammoth()
- >>> from zope.component import provideAdapter
- >>> provideAdapter(MammothSize)
- >>> from zope.size.interfaces import ISized
- >>> size = ISized(manfred)
- >>> size.sizeForDisplay()
- '1000 bytes'
+:func:`grok.implements` is currently an alias for
+:func:`zope.interface.implements`.
+**Example:** ::
- .. seealso::
+ >>> import grok
+ >>> from zope import interface
+ >>> class IPaintable(interface.Interface):
+ ... pass
+ ...
+ >>> class Cave(object):
+ ... pass
+ ...
+ >>> cave = Cave()
+ >>> IPaintable.providedBy(cave)
+ False
+ >>> class PaintableCave(object):
+ ... grok.implements(IPaintable)
+ ...
+ >>> cave = PaintableCave()
+ >>> IPaintable.providedBy(cave)
+ True
- :func:`grok.implements`
+:func:`grok.provides`
+=====================
+.. function:: grok.provides(interface)
-:func:`grok.baseclass` -- declare a class as base
-=================================================
+If the component implements more than one interface, :func:`grok.provides`
+is required to disambiguate for what interface the component will be
+registered.
+.. seealso::
-.. function:: grok.baseclass()
+ :func:`grok.implements`
- A class-level directive without argument to mark something as a
- base class. Base classes are are not grokked.
+:func:`grok.adapts` -- Declare that a class adapts certain objects
+==================================================================
- Another way to indicate that something is a base class, is by
- postfixing the classname with ``'Base'``.
+.. function:: grok.adapts(*classes_or_interfaces)
- The baseclass mark is not inherited by subclasses, so those
- subclasses will be grokked (except they are explicitly declared as
- baseclasses as well).
+A class-level directive to declare that a class adapts objects of the
+classes or interfaces given in `\*classes_or_interfaces`.
- **Example:** ::
+This directive accepts several arguments.
- import grok
+It works much like the :mod:`zope.component`\ s :func:`adapts()`, but you do
+not have to make a ZCML entry to register the adapter.
- class ModelBase(grok.Model):
- pass
+**Example:** ::
- class ViewBase(grok.View):
- def render(self):
- return "hello world"
+ import grok
+ from zope import interface, schema
+ from zope.size.interfaces import ISized
- class AnotherView(grok.View):
- grok.baseclass()
+ class IMammoth(interface.Interface):
+ name = schema.TextLine(title=u"Name")
+ size = schema.TextLine(title=u"Size", default=u"Quite normal")
- def render(self):
- return "hello world"
+ class Mammoth(grok.Model):
+ interface.implements(IMammoth)
- class WorkingView(grok.View):
- pass
+ class MammothSize(object):
+ grok.implements(ISized)
+ grok.adapts(IMammoth)
- Using this example, only the :class:`WorkingView` will serve as a
- view, while calling the :class:`ViewBase` or :class:`AnotherView`
- will lead to a :exc:`ComponentLookupError`.
+ def __init__(self, context):
+ self.context = context
+ def sizeForSorting(self):
+ return ('byte', 1000)
-:func:`grok.define_permission` -- define a permission
-=====================================================
+ def sizeForDisplay(self):
+ return ('1000 bytes')
+Having :class:`MammothSize` available, you can register it as an adapter,
+without a single line of ZCML::
-.. function:: grok.define_permission(name)
+ >>> manfred = Mammoth()
+ >>> from zope.component import provideAdapter
+ >>> provideAdapter(MammothSize)
+ >>> from zope.size.interfaces import ISized
+ >>> size = ISized(manfred)
+ >>> size.sizeForDisplay()
+ '1000 bytes'
- A module-level directive to define a permission with name
- `name`. Usually permission names are prefixed by a component- or
- application name and a dot to keep them unique.
+.. seealso::
- Because in Grok by default everything is accessible by everybody,
- it is important to define permissions, which restrict access to
- certain principals or roles.
+ :func:`grok.implements`
- **Example:** ::
+:func:`grok.baseclass` -- declare a class as base
+=================================================
- import grok
- grok.define_permission('cave.enter')
+.. function:: grok.baseclass()
+A class-level directive without argument to mark something as a base class.
+Base classes are are not grokked.
- .. seealso::
+Another way to indicate that something is a base class, is by postfixing the
+classname with ``'Base'``.
- :func:`grok.require`, :class:`grok.Permission`, :class:`grok.Role`
+The baseclass mark is not inherited by subclasses, so those subclasses will
+be grokked (except they are explicitly declared as baseclasses as well).
- .. versionchanged:: 0.11
- replaced by :class:`grok.Permission`.
+**Example:** ::
+ import grok
-:func:`grok.Fields` -- declare schema fields of a form
-======================================================
+ class ModelBase(grok.Model):
+ pass
-.. function:: grok.Fields(**schemas)
+ class ViewBase(grok.View):
+ def render(self):
+ return "hello world"
- A class level directive, which can be used inside :class:`grok.Form`
- classes.
+ class AnotherView(grok.View):
+ grok.baseclass()
- A :class:`grok.Fields` can receive keyword parameters with schema
- fields. These should be available in the definition order.
+ def render(self):
+ return "hello world"
- **Example:** ::
+ class WorkingView(grok.View):
+ pass
- import grok
- from zope import schema
+Using this example, only the :class:`WorkingView` will serve as a view,
+while calling the :class:`ViewBase` or :class:`AnotherView` will lead to a
+:exc:`ComponentLookupError`.
- class Mammoth(grok.Model):
- pass
+Utility directives
+~~~~~~~~~~~~~~~~~~
- class Edit(grok.EditForm):
- fields = grok.Fields(
- b = schema.TextLine(title=u"Beta"),
- a = schema.TextLine(title=u"Alpha"),
-
- Given the above code, when the :class:`Edit` form is rendered, the
- :class:`Textlines` `b` and `a` will appear as input fields in that
- order. This is due to the fact, that by default the `fields`
- variable is taken into account, when rendering forms.
-
- .. seealso::
-
- :func:`grok.AutoFields`, :class:`grok.Form`
-
-
-:func:`grok.implements` -- indicate, that a class implements an interface
-=========================================================================
-
-
-.. function:: grok.implements(*interfaces)
-
- A class level directive to declare one or more `interfaces`, as
- implementers of the surrounding class. This directive allows
- several parameters.
-
- :func:`grok.implements` is currently an alias for
- :func:`zope.interface.implements`.
-
- **Example:** ::
-
- >>> import grok
- >>> from zope import interface
- >>> class IPaintable(interface.Interface):
- ... pass
- ...
- >>> class Cave(object):
- ... pass
- ...
- >>> cave = Cave()
- >>> IPaintable.providedBy(cave)
- False
- >>> class PaintableCave(object):
- ... grok.implements(IPaintable)
- ...
- >>> cave = PaintableCave()
- >>> IPaintable.providedBy(cave)
- True
-
-
-:func:`grok.context` -- Declare the context for views, adapters, etc.
-=====================================================================
-
-
-.. function:: grok.context(*class_or_interface)
-
- A class or module level directive to indicate the context for
- something (class or module) in the same scope. When used on module
- level, it will set the context for all views, adapters, etc. in
- that module. When used on class level, it will set the context for
- that particular class.
-
- With Grok contexts are set automatically for some objects, if they
- are unambigous. For example a :class:`grok.View` will get the only
- :class:`grok.Application` or :class:`grok.Model` class as context,
- iff there exists exactly one in the same module. If there are more
- possible contexts or you want to set a type (class/interface) from
- another module as context, than the one choosen by default, then
- you have to call :func:`grok.context` explicitly.
-
- **Example:**
-
- Here the :func:`grok.context` directive indicates, that
- :class:`Mammoth` instances will be the context of :class:`Index`
- views (and not instances of :class:`Cave`) ::
-
-
- import grok
-
- class Mammoth(grok.Model):
- pass
-
- class Cave(grok.Model):
- pass
-
- class Index(grok.View):
- grok.context(Mammoth)
-
-
-
- .. seealso::
-
- :class:`grok.View`, :class:`grok.Adapter`, :class:`grok.MultiAdapter`
-
-
-
-
:func:`grok.global_utility` -- register a global utility
========================================================
-
.. function:: grok.global_utility(factory[, provides=None[, name=u'']])
- A module level directive to register a global utility.
+A module level directive to register a global utility.
- `factory` - the factory that creates the utility.
+`factory` - the factory that creates the utility.
- `provides` - the interface the utility should be looked up with.
+`provides` - the interface the utility should be looked up with.
- `name` - the name of the utility.
+`name` - the name of the utility.
- The latter two parameters are optional.
+The latter two parameters are optional.
- To register the utility correctly, Grok must be able to identify an
- interface provided by the utility. If none is given, Grok checks
- whether (exactly) one interface is implemented by the factory to be
- registered (see example below). If more than one interface is
- implemented by a class, use :func:`grok.provides` to specify which
- one to use. If no interface is implemented by the instances
- delivered by the factory, use :func:`grok.implements` to specify
- one.
+To register the utility correctly, Grok must be able to identify an
+interface provided by the utility. If none is given, Grok checks whether
+(exactly) one interface is implemented by the factory to be registered (see
+example below). If more than one interface is implemented by a class, use
+:func:`grok.provides` to specify which one to use. If no interface is
+implemented by the instances delivered by the factory, use
+:func:`grok.implements` to specify one.
- Another way to register global utilities with Grok is to subclass
- from :class:`grok.GlobalUtility`.
+Another way to register global utilities with Grok is to subclass from
+:class:`grok.GlobalUtility`.
+**Example:**
- **Example:**
+ Given the following module code: ::
- Given the following module code: ::
-
- import grok
- from zope import interface
-
- class IFireplace(interface.Interface):
- pass
-
- class Fireplace(object):
- grok.implements(IFireplace)
-
- grok.global_utility(Fireplace)
- grok.global_utility(Fireplace, name='hot')
-
- Then the following works: ::
-
- >>> from zope import component
- >>> fireplace = component.getUtility(IFireplace)
- >>> IFireplace.providedBy(fireplace)
- True
- >>> isinstance(fireplace, Fireplace)
- True
-
- >>> fireplace = component.getUtility(IFireplace, name='hot')
- >>> IFireplace.providedBy(fireplace)
- True
- >>> isinstance(fireplace, Fireplace)
- True
-
- .. seealso::
-
- :class:`grok.GlobalUtility`, :func:`grok.provides`,
- :func:`grok.implements`
-
-
-:func:`grok.name` -- associate a component with a name
-======================================================
-
-
-.. function:: grok.name(name)
-
- A class level directive used to associate a component with a single
- name `name`. Typically this directive is optional. The default behaviour
- when no name is given depends on the component. The same applies to
- the semantics of this directive: for what exactly a name is set
- when using this directive, depends on the component.
-
- **Example:** ::
-
import grok
+ from zope import interface
- class Mammoth(grok.Model):
- pass
+ class IFireplace(interface.Interface):
+ pass
- class Index(grok.View):
- grok.name('index')
+ class Fireplace(object):
+ grok.implements(IFireplace)
+ grok.global_utility(Fireplace)
+ grok.global_utility(Fireplace, name='hot')
- .. seealso::
+ Then the following works: ::
- :class:`grok.Adapter`, :class:`grok.Annotation`,
- :class:`grok.GlobalUtility`, :class:`grok.Indexes`,
- :class:`grok.MultiAdapter`, :class:`grok.Role`,
- :class:`grok.View`
+ >>> from zope import component
+ >>> fireplace = component.getUtility(IFireplace)
+ >>> IFireplace.providedBy(fireplace)
+ True
+ >>> isinstance(fireplace, Fireplace)
+ True
+ >>> fireplace = component.getUtility(IFireplace, name='hot')
+ >>> IFireplace.providedBy(fireplace)
+ True
+ >>> isinstance(fireplace, Fireplace)
+ True
+.. seealso::
+ :class:`grok.GlobalUtility`, :func:`grok.provides`,
+ :func:`grok.implements`
:func:`grok.local_utility` -- register a local utility
======================================================
-
.. function:: grok.local_utility(factory[, provides=None[, name=u''[, setup=None[, public=False[, name_in_container=None]]]]])
- A class level directive to register a local utility.
+A class level directive to register a local utility.
- `factory` -- the factory that creates the utility.
+`factory` -- the factory that creates the utility.
- `provides` -- the interface the utility should be looked up with.
+`provides` -- the interface the utility should be looked up with.
- `name` -- the name of the utility.
+`name` -- the name of the utility.
- `setup` -- a callable that receives the utility as its single
- argument, it is called after the utility has been created and
- stored.
+`setup` -- a callable that receives the utility as its single
+ argument, it is called after the utility has been created and
+ stored.
- `public` -- if `False`, the utility will be stored below
- `++etc++site`. If `True`, the utility will be stored directly
- in the site. The site should in this case be a container.
+`public` -- if `False`, the utility will be stored below
+ `++etc++site`. If `True`, the utility will be stored directly
+ in the site. The site should in this case be a container.
- `name_in_container` -- the name to use for storing the utility.
+`name_in_container` -- the name to use for storing the utility.
- All but the first parameter are optional.
+All but the first parameter are optional.
- To register a local utility correctly, Grok must know about the
- interface, the utility should be looked up with. If none is given,
- Grok looks up any interfaces implemented by instances delivered by
- `factory` and if exactly one can be found, it is taken. See
- :func:`grok.global_utility`.
+To register a local utility correctly, Grok must know about the interface,
+the utility should be looked up with. If none is given, Grok looks up any
+interfaces implemented by instances delivered by `factory` and if exactly
+one can be found, it is taken. See :func:`grok.global_utility`.
- Every single combination of interfaces and names can only be
- registered once per module.
+Every single combination of interfaces and names can only be registered once
+per module.
- It is not possible to declare a local utility as public, if the
- site is not a container. Grok will remind you of this. To store a
- utility in a container, a `name_in_container` is needed. If
- none is given, Grok will make up one automatically.
+It is not possible to declare a local utility as public, if the site is not
+a container. Grok will remind you of this. To store a utility in a
+container, a `name_in_container` is needed. If none is given, Grok will make
+up one automatically.
- An alternative way to define a local utility is to subclass from
- :class:`grok.LocalUtility`.
+An alternative way to define a local utility is to subclass from
+:class:`grok.LocalUtility`.
- **Example:**
+**Example:**
- The following code registers a local unnamed utility `fireplace` in
- instances of :class:`Cave` ::
+ The following code registers a local unnamed utility `fireplace` in
+ instances of :class:`Cave` ::
- import grok
- from zope import interface
+ import grok
+ from zope import interface
- class IFireplace(interface.Interface):
- pass
+ class IFireplace(interface.Interface):
+ pass
- class Fireplace(grok.LocalUtility):
- grok.implements(IFireplace)
+ class Fireplace(grok.LocalUtility):
+ grok.implements(IFireplace)
- class Cave(grok.Container, grok.Site):
- grok.local_utility(Fireplace, public=True,
- name_in_container='fireplace')
-
+ class Cave(grok.Container, grok.Site):
+ grok.local_utility(Fireplace, public=True,
+ name_in_container='fireplace')
- .. seealso::
+.. seealso::
- :func:`grok.global_utility`, :class:`grok.LocalUtility`
+ :func:`grok.global_utility`, :class:`grok.LocalUtility`
-
-:func:`grok.provides`
-=====================
-
-
-.. function:: grok.provides(*arg)
-
- foobar
-
-
:func:`grok.resourcedir --- XXX Not implemented yet`
====================================================
-
.. function:: grok.resourcedir(*arg)
foobar
- Resource directories are used to embed static resources like HTML-,
- JavaScript-, CSS- and other files in your application.
+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)
+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>`.
+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>`.
- **Example:**
+**Example:**
- The package :mod:`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`.
+The package :mod:`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`.
.. note::
- 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.
+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.
-
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::
<link rel="stylesheet" tal:attributes="href static/example.css" type="text/css">
-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.
+Security directives
+~~~~~~~~~~~~~~~~~~~
:func:`grok.require`
====================
+.. function:: grok.require(permission)
-.. function:: grok.require(*arg)
+A class level directive used to protect a View by requiring a certain permission.
- foobar
+`permission` -- the name of the permission that is required
+** Example **::
-:func:`grok.site`
-=================
+ class ViewPainting(grok.Permission):
+ grok.name('grok.ViewPainting')
+
+.. seealso::
-.. function:: grok.site(*arg)
+ :class:`grok.Permission` component, :func:`@grok.require` decorator
- foobar
+Template directives
+~~~~~~~~~~~~~~~~~~~
:func:`grok.template`
=====================
+.. function:: grok.template(template)
-.. function:: grok.template(*arg)
+A class level directive used to specify the template to be rendered for the View when no render method is defined.
- foobar
+`template` -- name of the template file
+** Convention **
+When not specified, Grok will look for a template file with the same name as the view class itself, lowercased, in the templates directory for this module.
+
+.. seealso::
+
+ :func:`grok.templatedir`
+
:func:`grok.templatedir`
========================
+A module level directive used to specify the directory where Grok should look for template files.
-.. function:: grok.templatedir(*arg)
+.. function:: grok.templatedir(directory)
- foobar
+`directory` -- the name of the directory inside the same package as the module
+** Convention **
-:func:`grok.title`
-========================
+When not specified, Grok will look template files in a diretory named `<module>_templates` where `<module>` is the name of the current module.
+.. seealso::
-.. function:: grok.title(*arg)
+ :func:`grok.template`
- foobar
+Uncategorized directives
+~~~~~~~~~~~~~~~~~~~~~~~~
+:func:`grok.site`
+=================
+
+.. function:: grok.site(*arg)
+
+A class level directive used in `grok.Indexes` sub-classes to define in which local component registry the indexes should be located.
+
+** Example **
+::
+
+ class MammothIndexes(grok.Indexes):
+ grok.site(Herd)
+ grok.context(IMammoth)
+
+ name = index.Field()
Modified: grok/trunk/doc/reference/functions.rst
===================================================================
--- grok/trunk/doc/reference/functions.rst 2007-10-05 14:34:02 UTC (rev 80653)
+++ grok/trunk/doc/reference/functions.rst 2007-10-05 14:46:05 UTC (rev 80654)
@@ -7,8 +7,86 @@
common tasks.
+:func:`grok.AutoFields` -- Deduce and return schema fields automatically
+========================================================================
+
+
+.. function:: grok.AutoFields(class_or_interface)
+
+ This function which can be used inside :class:`Form`
+ classes to automatically deduce the form fields from the schema of
+ the context `class_or_interface`.
+
+ Different to most other directives, :func:`grok.AutoFields` is used
+ more like a function and less like a pure declaration.
+
+ This function is used to create a sequence of form fields from an interface
+ (schema) or from the interfaces (schemas) the context object provides.
+
+ The following example makes use of the :func:`grok.AutoFields`
+ directive, in that one field is omitted from the form before
+ rendering:
+
+**Example:** ::
+
+ 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')
+
+In this example the ``size`` attribute will not show up in the
+resulting edit view.
+
+
+.. seealso::
+
+ :class:`grok.EditForm`, :func:`grok.Fields`
+
+:func:`grok.Fields` -- declare schema fields of a form
+======================================================
+
+.. function:: grok.Fields(**schemas)
+
+ A class level directive, which can be used inside :class:`grok.Form`
+ classes.
+
+ A :class:`grok.Fields` can receive keyword parameters with schema
+ fields. These should be available in the definition order.
+
+ **Example:** ::
+
+ import grok
+ from zope import schema
+
+ class Mammoth(grok.Model):
+ pass
+
+ class Edit(grok.EditForm):
+ fields = grok.Fields(
+ b = schema.TextLine(title=u"Beta"),
+ a = schema.TextLine(title=u"Alpha"),
+
+ Given the above code, when the :class:`Edit` form is rendered, the
+ :class:`Textlines` `b` and `a` will appear as input fields in that
+ order. This is due to the fact, that by default the `fields`
+ variable is taken into account, when rendering forms.
+
+ .. seealso::
+
+ :func:`grok.AutoFields`, :class:`grok.Form`
+
:func:`grok.getSite`
-====================
+===============================================
.. function:: grok.getSite()
@@ -79,3 +157,44 @@
View classes derived from :class:`grok.View` have a similar :meth:`url` method
for constructing URLs.
+
+:func:`grok.grok` -- Grok a package or module
+=============================================
+
+
+.. function:: grok(dotted_name)
+
+.. note:: Usually you don't need to invoke this funtion in your code, since it's triggered from the `configure.zcml`. Grokking test fixtures is one situation where it is useful to call this explicitly.
+
+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 `dotted_name` must specify either a Python module or package that is
+available from the current PYTHONPATH.
+
+Grokking a module:
+
+#. Scan the module for known components: models, adapters, utilities, views,
+ traversers, templates and subscribers.
+
+#. Check whether a directory with file system templates exists
+(:file:`<modulename>_templates`). If it exists, load the file system templates
+into the template registry for this module.
+
+#. Determine the module context.
+
+#. Register all components with the Zope 3 component architecture.
+
+#. Initialize schemata for registered models
+
+ Grokking a package:
+
+#. Grok the package as a module.
+
+#. Check for a static resource directory (:file:`static`) and register it if
+it exists.
+
+#. Recursively grok all sub-modules and sub-packages.
+
+
More information about the Checkins
mailing list