[Zope3-checkins]
SVN: Zope3/branches/ZopeX3-3.0/src/zope/app/form/browser/
Make the ReST markup more consistent with other ReST in Zope 3.
Fred L. Drake, Jr.
fred at zope.com
Fri Jul 16 15:01:59 EDT 2004
Log message for revision 26588:
Make the ReST markup more consistent with other ReST in Zope 3.
Changed:
U Zope3/branches/ZopeX3-3.0/src/zope/app/form/browser/README.txt
U Zope3/branches/ZopeX3-3.0/src/zope/app/form/browser/complexsample/README.txt
U Zope3/branches/ZopeX3-3.0/src/zope/app/form/browser/widgets.txt
-=-
Modified: Zope3/branches/ZopeX3-3.0/src/zope/app/form/browser/README.txt
===================================================================
--- Zope3/branches/ZopeX3-3.0/src/zope/app/form/browser/README.txt 2004-07-16 19:01:09 UTC (rev 26587)
+++ Zope3/branches/ZopeX3-3.0/src/zope/app/form/browser/README.txt 2004-07-16 19:01:59 UTC (rev 26588)
@@ -3,10 +3,10 @@
===============
This directory contains widgets: views on bound schema fields. Many of these
-are straightforward. For instance, see the TextWidget in textwidgets.py, which
-is a subclass of BrowserWidget in widget.py. It is registered as an
-IBrowserRequest view of an ITextLine schema field, providing the IInputWidget
-interface::
+are straightforward. For instance, see the `TextWidget` in textwidgets.py,
+which is a subclass of BrowserWidget in widget.py. It is registered as an
+`IBrowserRequest` view of an `ITextLine` schema field, providing the
+`IInputWidget` interface::
<view
type="zope.publisher.interfaces.browser.IBrowserRequest"
@@ -17,26 +17,26 @@
/>
The widget then receives the field and the request as arguments to the factory
-(i.e., the TextWidget class).
+(i.e., the `TextWidget` class).
Some widgets in Zope 3 extend this pattern. This extension is configurable:
simply do not load the zope/app/form/browser/configure.zcml file if you do not
wish to participate in the extension. The widget registration is extended for
-Choice fields and for the collection fields.
+`Choice` fields and for the collection fields.
Default Choice Field Widget Registration and Lookup
===================================================
As described above, all field widgets are obtained by looking up a browser
-IInputWidget or IDisplayWidget view for the field object. For Choice fields,
-the default registered widget defers all of its behavior to the result of
-another lookup: a browser widget view for the field *and* the Choice field's
+`IInputWidget` or `IDisplayWidget` view for the field object. For `Choice`
+fields, the default registered widget defers all of its behavior to the result
+of another lookup: a browser widget view for the field *and* the Choice field's
vocabulary.
This allows registration of Choice widgets that differ on the basis of the
vocabulary type. For example, a widget for a vocabulary of images might have
a significantly different user interface than a widget for a vocabulary of
-words. A dynamic vocabulary might implement IIterableVocabulary if its
+words. A dynamic vocabulary might implement `IIterableVocabulary` if its
contents are below a certain length, but not implement the marker "iterable"
interface if the number of possible values is above the threshhold.
@@ -45,12 +45,12 @@
arguments, choice widgets receive the field, vocabulary, and request as
arguments.
-Some Choice widgets may also need to provide a query interface, particularly if
-the number of items in the vocabuary are too big to iterate. The vocabulary
+Some `Choice` widgets may also need to provide a query interface, particularly
+if the number of items in the vocabuary are too big to iterate. The vocabulary
may provide a query which implements an interface appropriate for that
vocabulary. You then can register a query view--a view registered for the
query interface and the field interface--that implements
-zope.app.forms.browser.interfaces.IVocabularyQueryView.
+`zope.app.forms.browser.interfaces.IVocabularyQueryView`.
Default Collection Field Widget Registration and Lookup
=======================================================
@@ -58,36 +58,36 @@
The default configured lookup for collection fields--List, Tuple, and Set, for
instance--begins with the usual lookup for a browser widget view for the
field object. This widget defers its display to the result of another lookup:
-a browser widget view registered for the field and the field's value_type (the
-type of the contained values). This allows registrations for collection
+a browser widget view registered for the field and the field's `value_type`
+(the type of the contained values). This allows registrations for collection
widgets that differ on the basis of the members--a widget for entering a list
of text strings might differ significantly from a widget for entering a list of
dates...or even a list of choices, as discussed below.
This registration pattern has three implications that should be highlighted.
- * First, collection fields that do not specify a value_type probably cannot
- have a reasonable widget.
+* First, collection fields that do not specify a `value_type` probably cannot
+ have a reasonable widget.
- * Second, collection widgets that wish to be the default widget for a
- collection with any value_type should be registered for the collection
- field and a generic value_type: the IField interface. Do not register the
- generic widget for the collection field only or you will break the lookup
- behavior as described here.
-
- * Third, like choice widget factories, sequence widget factories (classes or
- functions) take three arguments. Typical sequence widgets receive the
- field, the value_type, and the request as arguments.
+* Second, collection widgets that wish to be the default widget for a
+ collection with any `value_type` should be registered for the collection
+ field and a generic value_type: the `IField` interface. Do not register the
+ generic widget for the collection field only or you will break the lookup
+ behavior as described here.
+* Third, like choice widget factories, sequence widget factories (classes or
+ functions) take three arguments. Typical sequence widgets receive the
+ field, the `value_type`, and the request as arguments.
+
Collections of Choices
----------------------
-If a collection field's value_type is a Choice field, the second widget again
-defers its behavior, this time to a third lookup based on the collection field
-and the choice's vocabulary. This means that a widget for a list of large
-image choices can be different than a widget for a list of small image choices
-(with a different vocabulary interface), different from a widget for a list of
-keyword choices, and different from a set of keyword choices.
+If a collection field's `value_type` is a `Choice` field, the second widget
+again defers its behavior, this time to a third lookup based on the collection
+field and the choice's vocabulary. This means that a widget for a list of
+large image choices can be different than a widget for a list of small image
+choices (with a different vocabulary interface), different from a widget for a
+list of keyword choices, and different from a set of keyword choices.
Some advanced applications may wish to do a further lookup on the basis of the
unique attribute of the collection field--perhaps looking up a named view with
@@ -105,7 +105,7 @@
The only hard requirement is that the developer must register the bag + choice
widget: the widget is just the factory for the third dispatch as described
-above, so the developer can use the already implemented widgets listed below.
+above, so the developer can use the already implemented widgets listed below::
<view
type="zope.publisher.interfaces.browser.IBrowserRequest"
@@ -127,7 +127,7 @@
Beyond this, the developer may also have a generic bag widget she wishes to
register. This might look something like this, assuming there's a
-BagSequenceWidget available in this package::
+`BagSequenceWidget` available in this package::
<view
type="zope.publisher.interfaces.browser.IBrowserRequest"
@@ -139,8 +139,8 @@
/>
Then any widgets for the bag and a vocabulary would be registered according to
-this general pattern, in which IIterableVocabulary would be the interface of
-any appropriate vocabulary and BagWidget is some appropriate widget::
+this general pattern, in which `IIterableVocabulary` would be the interface of
+any appropriate vocabulary and `BagWidget` is some appropriate widget::
<view
type="zope.publisher.interfaces.browser.IBrowserRequest"
Modified: Zope3/branches/ZopeX3-3.0/src/zope/app/form/browser/complexsample/README.txt
===================================================================
--- Zope3/branches/ZopeX3-3.0/src/zope/app/form/browser/complexsample/README.txt 2004-07-16 19:01:09 UTC (rev 26587)
+++ Zope3/branches/ZopeX3-3.0/src/zope/app/form/browser/complexsample/README.txt 2004-07-16 19:01:59 UTC (rev 26588)
@@ -20,7 +20,7 @@
kind of query behaviors the sample widget expects.
widgetapi.py
- Alternate base implementation of the IBrowserWidget interface.
+ Alternate base implementation of the `IBrowserWidget` interface.
This completely bypasses the implementation from the
- zope.app.form.browser.widget module, and is really designed for
+ `zope.app.form.browser.widget` module, and is really designed for
use with widgets of the sort demonstrated in this package.
Modified: Zope3/branches/ZopeX3-3.0/src/zope/app/form/browser/widgets.txt
===================================================================
--- Zope3/branches/ZopeX3-3.0/src/zope/app/form/browser/widgets.txt 2004-07-16 19:01:09 UTC (rev 26587)
+++ Zope3/branches/ZopeX3-3.0/src/zope/app/form/browser/widgets.txt 2004-07-16 19:01:59 UTC (rev 26588)
@@ -5,14 +5,14 @@
zope/app/demo/poll) which has poll options defined as:
label
- A TextLine holding the label of the option
+ A `TextLine` holding the label of the option
description
- Another TextLine holding the description of the option
+ Another `TextLine` holding the description of the option
Simple stuff.
-Our Poll product holds an editable list of the PollOption instances. This
-is shown in the ``poll.py`` source below::
+Our Poll product holds an editable list of the `PollOption` instances.
+This is shown in the ``poll.py`` source below::
from persistent import Persistent
from interfaces import IPoll, IPollOption
@@ -42,7 +42,7 @@
options = property(get_options, set_options, None, 'fiddle options')
-And the Schemas are define in the ``interfaces.py`` file below::
+And the Schemas are defined in the ``interfaces.py`` file below::
from zope.interface import Interface
from zope.schema import Object, Tuple, TextLine
@@ -63,10 +63,11 @@
def choose(option): 'user chooses an option'
-Note the use of the Tuple and Object schema fields above. The Tuple
-could optionally have restrictions on the min or max number of items -
-these will be enforce by the SequenceWidget form handling code. The Object
-must specify the schema that is used to generate its data.
+Note the use of the `Tuple` and `Object` schema fields above. The
+`Tuple` could optionally have restrictions on the min or max number of
+items - these will be enforced by the `SequenceWidget` form handling
+code. The `Object` must specify the schema that is used to generate its
+data.
Now we have to specify the actual add and edit views. We use the existing
AddView and EditView, but we pre-define the widget for the sequence because
@@ -107,20 +108,20 @@
options_widget = sw
-Note the creation of the widget via a CustomWidgetFactory. So,
+Note the creation of the widget via a `CustomWidgetFactory`. So,
whenever the options_widget is used, a new
``SequenceWidget(subwidget=CustomWidgetFactory(ObjectWidget,
PollOption))`` is created. The subwidget argument indicates that each
item in the sequence should be represented by the indicated widget
instead of their default. If the contents of the sequence were just
-Text Fields, then the default would be just fine - the only odd cases
+`Text` fields, then the default would be just fine - the only odd cases
are Sequence and Object Widgets because they need additional arguments
when they're created.
Each item in the sequence will be represented by a
``CustomWidgetFactory(ObjectWidget, PollOption)`` - thus a new
``ObjectWidget(context, request, PollOption)`` is created for each
-one. The PollOption class ("factory") is used to create new instances
+one. The `PollOption` class ("factory") is used to create new instances
when new data is created in add forms (or edit forms when we're adding
new items to a Sequence).
@@ -190,10 +191,10 @@
</configure>
-Note the use of the "class" argument to the addform and editform
-directives. Otherwise, nothing much exciting here.
+Note the use of the ``class`` attribute on the ``addform`` and
+``editform`` elements. Otherwise, nothing much exciting here.
-Finally, we have some additiona views...
+Finally, we have some additional views...
``results.zpt``::
More information about the Zope3-Checkins
mailing list