[Checkins] SVN: Sandbox/ulif/grok-reference-with-rest/doc/reference/directives.rst Documented some more directives.

Uli Fouquet uli at gnufix.de
Wed Sep 26 19:46:12 EDT 2007


Log message for revision 80172:
  Documented some more directives.

Changed:
  U   Sandbox/ulif/grok-reference-with-rest/doc/reference/directives.rst

-=-
Modified: Sandbox/ulif/grok-reference-with-rest/doc/reference/directives.rst
===================================================================
--- Sandbox/ulif/grok-reference-with-rest/doc/reference/directives.rst	2007-09-26 23:41:50 UTC (rev 80171)
+++ Sandbox/ulif/grok-reference-with-rest/doc/reference/directives.rst	2007-09-26 23:46:11 UTC (rev 80172)
@@ -13,61 +13,62 @@
 in question.
 
 
-:func:`grok.AutoFields` -- deduce schema fields automatically
+:func:`grok.AutoFields` -- Deduce schema fields automatically
 =============================================================
 
 
 .. function:: 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
-   `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`.
 
-   Different to most other directives, :func:`grok.AutoFields` is used more like a
-   function and less like a pure declaration.
+   Different to most other directives, :func:`grok.AutoFields` is used
+   more like a function and less like a pure declaration.
 
-   The following example makes use of the :func:`grok.AutoFields` directive, in
-   that one field is omitted from the form before rendering:
+   The following example makes use of the :func:`grok.AutoFields`
+   directive, in that one field is omitted from the form before
+   rendering:
 
-   **Example:** ::
+**Example:** ::
 
-      import grok
-      from zope import interface, schema
+   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 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 Mammoth(grok.Model):
+       interface.implements(IMammoth)
 
-      class Edit(grok.EditForm):
-          grok.context(Mammoth)
+   class Edit(grok.EditForm):
+       grok.context(Mammoth)
 
-          form_fields = grok.AutoFields(Mammoth).omit('size')
+       form_fields = grok.AutoFields(Mammoth).omit('size')
 
-   In this example the ``size`` attribute will not show up in the resulting edit
-   view.
+In this example the ``size`` attribute will not show up in the
+resulting edit view.
 
 
-   .. seealso::
+.. seealso::
 
-      :class:`grok.EditForm`, :class:`grok.Fields`
+   :class:`grok.EditForm`, :func:`grok.Fields`
 
 
-:func:`grok.adapts` -- declare that a class adapts certain objects
+: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:** ::
 
@@ -109,7 +110,7 @@
 
    .. seealso::
 
-      :class:`grok.implements`
+      :func:`grok.implements`
 
 
 :func:`grok.baseclass` -- declare a class as base
@@ -118,14 +119,15 @@
 
 .. 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:** ::
 
@@ -147,9 +149,9 @@
       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`.
 
 
 :func:`grok.define_permission` -- define a permission
@@ -158,13 +160,13 @@
 
 .. 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.
+   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.
+   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:** ::
 
@@ -174,39 +176,126 @@
 
    .. seealso::
 
-      :func:`grok.require()`, :class:`grok.Permission`, :class:`grok.Role`
+      :func:`grok.require`, :class:`grok.Permission`, :class:`grok.Role`
 
    .. versionchanged:: 0.11
       replaced by :class:`grok.Permission`.
 
 
-:func:`grok.Fields`
-===================
+:func:`grok.Fields` -- declare schema fields of a form
+======================================================
 
+.. function:: grok.Fields(**schemas)
 
-.. function:: grok.Fields(*arg)
+   A class level directive, which can be used inside :class:`grok.Form`
+   classes.
 
-   foobar
+   A :class:`grok.Fields` can receive keyword parameters with schema
+   fields. These should be available in the definition order.
 
+   **Example:** ::
 
-:func:`grok.implements`
-=======================
+      import grok
+      from zope import schema
 
+      class Mammoth(grok.Model):
+          pass
 
-.. function:: grok.implements(*arg)
+      class Edit(grok.EditForm):
+          fields = grok.Fields(
+              b = schema.TextLine(title=u"Beta"),
+              a = schema.TextLine(title=u"Alpha"),
 
-   foobar
+   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.context`
-====================
+      :func:`grok.AutoFields`, :class:`grok.Form`
 
 
-.. function:: grok.context(*arg)
+:func:`grok.implements` -- indicate, that a class implements an interface
+=========================================================================
 
-   foobar
 
+.. function:: grok.implements(*interfaces)
 
+   A class level directive to declare one or more `interfaces`, as
+   implementers of the surrounding class.
+
+   :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`
 ===========================
 
@@ -224,8 +313,9 @@
 
    foobar
 
-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.
+   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.
 
 
 :func:`grok.local_utility`
@@ -254,38 +344,44 @@
 
    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:** 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`.
+   **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`.
+
 .. 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">
+<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.
 
 
 :func:`grok.require`



More information about the Checkins mailing list