[Checkins]
SVN: grok/branches/neanderthal-reference-documentation/doc/reference/
Rearanging the reference structure.
Jan-Wijbrand Kolman
janwijbrand at gmail.com
Mon Oct 1 12:56:44 EDT 2007
Log message for revision 80448:
Rearanging the reference structure.
Changed:
U grok/branches/neanderthal-reference-documentation/doc/reference/components.rst
U grok/branches/neanderthal-reference-documentation/doc/reference/directives.rst
U grok/branches/neanderthal-reference-documentation/doc/reference/functions.rst
-=-
Modified: grok/branches/neanderthal-reference-documentation/doc/reference/components.rst
===================================================================
--- grok/branches/neanderthal-reference-documentation/doc/reference/components.rst 2007-10-01 16:55:03 UTC (rev 80447)
+++ grok/branches/neanderthal-reference-documentation/doc/reference/components.rst 2007-10-01 16:56:43 UTC (rev 80448)
@@ -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/branches/neanderthal-reference-documentation/doc/reference/directives.rst
===================================================================
--- grok/branches/neanderthal-reference-documentation/doc/reference/directives.rst 2007-10-01 16:55:03 UTC (rev 80447)
+++ grok/branches/neanderthal-reference-documentation/doc/reference/directives.rst 2007-10-01 16:56:43 UTC (rev 80448)
@@ -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,63 +17,143 @@
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
+ import grok
- class IMammoth(interface.Interface):
- name = schema.TextLine(title=u"Name")
- size = schema.TextLine(title=u"Size", default=u"Quite normal")
+ class Mammoth(grok.Model):
+ pass
- class Mammoth(grok.Model):
- interface.implements(IMammoth)
+ class Cave(grok.Model):
+ pass
- class Edit(grok.EditForm):
- grok.context(Mammoth)
+ class Index(grok.View):
+ grok.context(Mammoth)
- form_fields = grok.AutoFields(Mammoth).omit('size')
+ .. seealso::
-In this example the ``size`` attribute will not show up in the
-resulting edit view.
+ :class:`grok.View`, :class:`grok.Adapter`, :class:`grok.MultiAdapter`
+:func:`grok.name` -- associate a component with a name
+======================================================
-.. seealso::
+.. function:: grok.name(name)
- :class:`grok.EditForm`, :func:`grok.Fields`
+ 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
+
+ class Mammoth(grok.Model):
+ pass
+
+ # 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')
+
+
+ .. seealso::
+
+ :class:`grok.Adapter`, :class:`grok.Annotation`,
+ :class:`grok.GlobalUtility`, :class:`grok.Indexes`,
+ :class:`grok.MultiAdapter`, :class:`grok.Role`,
+ :class:`grok.View`
+
+:func:`grok.title`
+========================
+
+.. function:: grok.title(*arg)
+
+ foobar
+
+: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.provides`
+=====================
+
+.. function:: grok.provides(interface)
+
+ If the component implements more than one interface, :func:`grok.provides`
+ is required to disambiguate for what interface the component will be
+ registered.
+
+ .. seealso::
+
+ :func:`grok.implements`
+
:func:`grok.adapts` -- Declare that a class adapts certain objects
==================================================================
-
.. function:: grok.adapts(*classes_or_interfaces)
- A class-level directive to declare that a class adapts objects of
- the classes or interfaces given in `\*classes_or_interfaces`.
+ A class-level directive to declare that a class adapts objects of the
+ classes or interfaces given in `\*classes_or_interfaces`.
This directive accepts several arguments.
- 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.
+ 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.
**Example:** ::
@@ -107,27 +192,23 @@
>>> size.sizeForDisplay()
'1000 bytes'
-
.. seealso::
:func:`grok.implements`
-
:func:`grok.baseclass` -- declare a class as base
=================================================
-
.. function:: grok.baseclass()
- A class-level directive without argument to mark something as a
- base class. Base classes are are not grokked.
+ 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 ``'Base'``.
+ Another way to indicate that something is a base class, is by postfixing the
+ classname with ``'Base'``.
- The baseclass mark is not inherited by subclasses, so those
- subclasses will be grokked (except they are explicitly declared as
- baseclasses as well).
+ The baseclass mark is not inherited by subclasses, so those subclasses will
+ be grokked (except they are explicitly declared as baseclasses as well).
**Example:** ::
@@ -149,158 +230,16 @@
class WorkingView(grok.View):
pass
- 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`.
+ 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`.
+Utility directives
+~~~~~~~~~~~~~~~~~~
-:func:`grok.define_permission` -- define a permission
-=====================================================
-
-
-.. function:: grok.define_permission(name)
-
- 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.
-
- Because in Grok by default everything is accessible by everybody,
- it is important to define permissions, which restrict access to
- certain principals or roles.
-
- **Example:** ::
-
- import grok
- grok.define_permission('cave.enter')
-
-
- .. seealso::
-
- :func:`grok.require`, :class:`grok.Permission`, :class:`grok.Role`
-
- .. versionchanged:: 0.11
- replaced by :class:`grok.Permission`.
-
-
-: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.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.
@@ -311,21 +250,19 @@
`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.
+ 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:**
Given the following module code: ::
@@ -350,7 +287,7 @@
True
>>> isinstance(fireplace, Fireplace)
True
-
+
>>> fireplace = component.getUtility(IFireplace, name='hot')
>>> IFireplace.providedBy(fireplace)
True
@@ -359,47 +296,12 @@
.. seealso::
- :class:`grok.GlobalUtility`, :func:`grok.provides`,
+ :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
-
- class Mammoth(grok.Model):
- pass
-
- class Index(grok.View):
- grok.name('index')
-
-
- .. seealso::
-
- :class:`grok.Adapter`, :class:`grok.Annotation`,
- :class:`grok.GlobalUtility`, :class:`grok.Indexes`,
- :class:`grok.MultiAdapter`, :class:`grok.Role`,
- :class:`grok.View`
-
-
-
-
: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.
@@ -420,21 +322,20 @@
`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`.
@@ -454,28 +355,16 @@
grok.implements(IFireplace)
class Cave(grok.Container, grok.Site):
- grok.local_utility(Fireplace, public=True,
+ grok.local_utility(Fireplace, public=True,
name_in_container='fireplace')
-
.. seealso::
: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
@@ -483,84 +372,70 @@
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
+ 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(*arg)
foobar
+Template directives
+~~~~~~~~~~~~~~~~~~~
-:func:`grok.site`
-=================
-
-
-.. function:: grok.site(*arg)
-
- foobar
-
-
:func:`grok.template`
=====================
-
.. function:: grok.template(*arg)
foobar
-
:func:`grok.templatedir`
========================
-
.. function:: grok.templatedir(*arg)
foobar
+Uncategorized directives
+~~~~~~~~~~~~~~~~~~~~~~~~
-:func:`grok.title`
-========================
+:func:`grok.site`
+=================
+.. function:: grok.site(*arg)
-.. function:: grok.title(*arg)
-
foobar
-
Modified: grok/branches/neanderthal-reference-documentation/doc/reference/functions.rst
===================================================================
--- grok/branches/neanderthal-reference-documentation/doc/reference/functions.rst 2007-10-01 16:55:03 UTC (rev 80447)
+++ grok/branches/neanderthal-reference-documentation/doc/reference/functions.rst 2007-10-01 16:56:43 UTC (rev 80448)
@@ -7,6 +7,84 @@
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`
====================
More information about the Checkins
mailing list