[Checkins] SVN: bluebream/website/docs/v1.0/ bit cleanup
Baiju M
baiju.m.mail at gmail.com
Wed Aug 11 22:32:35 EDT 2010
Log message for revision 115640:
bit cleanup
Changed:
U bluebream/website/docs/v1.0/community/index.rst
U bluebream/website/docs/v1.0/dev/index.rst
U bluebream/website/docs/v1.0/howto/index.rst
U bluebream/website/docs/v1.0/introduction.rst
U bluebream/website/docs/v1.0/manual/browserpage.rst
U bluebream/website/docs/v1.0/manual/browserresource.rst
U bluebream/website/docs/v1.0/manual/index.rst
U bluebream/website/docs/v1.0/manual/interface.rst
U bluebream/website/docs/v1.0/manual/schema.rst
U bluebream/website/docs/v1.0/new/index.rst
U bluebream/website/docs/v1.0/reference/index.rst
-=-
Modified: bluebream/website/docs/v1.0/community/index.rst
===================================================================
--- bluebream/website/docs/v1.0/community/index.rst 2010-08-11 18:37:22 UTC (rev 115639)
+++ bluebream/website/docs/v1.0/community/index.rst 2010-08-12 02:32:34 UTC (rev 115640)
@@ -2,7 +2,6 @@
====================================
.. toctree::
- :numbered:
:maxdepth: 2
browserresource
Modified: bluebream/website/docs/v1.0/dev/index.rst
===================================================================
--- bluebream/website/docs/v1.0/dev/index.rst 2010-08-11 18:37:22 UTC (rev 115639)
+++ bluebream/website/docs/v1.0/dev/index.rst 2010-08-12 02:32:34 UTC (rev 115640)
@@ -6,7 +6,6 @@
which is actually used by the developers.
.. toctree::
- :numbered:
:maxdepth: 2
contributing
Modified: bluebream/website/docs/v1.0/howto/index.rst
===================================================================
--- bluebream/website/docs/v1.0/howto/index.rst 2010-08-11 18:37:22 UTC (rev 115639)
+++ bluebream/website/docs/v1.0/howto/index.rst 2010-08-12 02:32:34 UTC (rev 115640)
@@ -2,7 +2,6 @@
======
.. toctree::
- :numbered:
:maxdepth: 2
defaultview
Modified: bluebream/website/docs/v1.0/introduction.rst
===================================================================
--- bluebream/website/docs/v1.0/introduction.rst 2010-08-11 18:37:22 UTC (rev 115639)
+++ bluebream/website/docs/v1.0/introduction.rst 2010-08-12 02:32:34 UTC (rev 115640)
@@ -156,8 +156,8 @@
of the ZCA. The Zope community has responded to this in with several
rapidly deployable ZCA-derived frameworks, which implement Convention over
configuration while maintaining the power of ZCA under the hood. Notable
-among these are :term:Grok: and Repoze. Take a look at the recent uploads
-to the PyPi site, it is rare to not see several zca projects listed.
+among these are :term:`Grok`: and Repoze. Take a look at the recent uploads
+to the PyPI site, it is rare to not see several ZCA projects listed.
.. _Convention over configuration: http://en.wikipedia.org/wiki/Convention_over_configuration
@@ -282,6 +282,8 @@
world-wide community. We thank you all. Please help us add more names to
the list of contributor as we move forward from January 2010.
+:ref:`List of contributors <contributors-start>`
+
.. _intro-translations:
Translations
@@ -289,8 +291,6 @@
- `Russian <http://bit.ly/92jl9Q>`_
-:ref:`contributors-start`
-
.. raw:: html
<div id="disqus_thread"></div><script type="text/javascript"
Modified: bluebream/website/docs/v1.0/manual/browserpage.rst
===================================================================
--- bluebream/website/docs/v1.0/manual/browserpage.rst 2010-08-11 18:37:22 UTC (rev 115639)
+++ bluebream/website/docs/v1.0/manual/browserpage.rst 2010-08-12 02:32:34 UTC (rev 115640)
@@ -8,20 +8,18 @@
Introduction
------------
-In the last chapter we have seen how to use resources HTML. The
-resource HTML will be only available on site-level with the ``@@``
-prefix. Where as browser pages are accessed with a single ``@`` just
-before the page name.
+In the last chapter we have seen how to use resources HTML. The resource
+HTML will be only available on site-level with the ``@@`` prefix. Where as
+browser pages are accessed with a single ``@`` just before the page name.
-Browser page (or more generically views) are representations for
-particular objects/components.
+Browser page (or more generically views) are representations for particular
+objects/components.
If you have a template like this (``helloworld.pt``)::
Hello, World !
-To register a page with the above template for an ``IFolder``
-interface::
+To register a page with the above template for an ``IFolder`` interface::
<browser:page
name="helloworld.html"
@@ -30,22 +28,22 @@
permission="zope.Public"
/>
-The ``browser:page`` directive is used to register browser pages.
-The `name` attribute specify the name of page which is used in the
-URL. The above page can be accessed like this:
-``http://localhost:8080/@helloworld.html``
+The ``browser:page`` directive is used to register browser pages. The
+`name` attribute specify the name of page which is used in the URL. The
+above page can be accessed from this URL:
+http://localhost:8080/@helloworld.html
.. _man-browser-view:
View components
---------------
-While templates display data view components are preparing data.
-View components convert data to output formats also prepare related
-data (meta-data). Then, create TAL-friendly object structures (dicts
-and lists). View components know about: component for which the
-representation is created (context) and request object holding all
-`output media` information (request)
+While templates display data view components are preparing data. View
+components convert data to output formats also prepare related data
+(meta-data). Then, create TAL-friendly object structures (dicts and lists).
+View components know about: component for which the representation is
+created (context) and request object holding all `output media` information
+(request)
Implementation
@@ -56,32 +54,34 @@
Here is a simple view defined::
+ from zope.formlib import form
from zope.formlib import DisplayForm
from zope.site.interfaces import IFolder
class HelloWorld(DisplayForm):
+ form_fields = form.Fields(IHelloWorld)
+
def subFolderIds(self):
for name, subobj in self.context.items():
if IFolder.providedBy(subobj):
yield name
-Since methods and attributes of the view component are directly used
-by the template, they should return simple iterable objects
-(e.g. lists, tuples, generators) or mappings (e.g. dicts).
+Since methods and attributes of the view component are directly used by the
+template, they should return simple iterable objects (e.g. lists, tuples,
+generators) or mappings (e.g. dicts).
.. _man-browser-conclusion:
Conclusion
----------
-This chapter created introduced Browser pages (or views).
+This chapter introduced Browser pages.
.. raw:: html
<div id="disqus_thread"></div><script type="text/javascript"
src="http://disqus.com/forums/bluebream/embed.js"></script><noscript><a
- href="http://disqus.com/forums/bluebream/?url=ref">View the
- discussion thread.</a></noscript><a href="http://disqus.com"
- class="dsq-brlink">blog comments powered by <span
- class="logo-disqus">Disqus</span></a>
+ href="http://disqus.com/forums/bluebream/?url=ref">View the discussion
+ thread.</a></noscript><a href="http://disqus.com" class="dsq-brlink">blog
+ comments powered by <span class="logo-disqus">Disqus</span></a>
Modified: bluebream/website/docs/v1.0/manual/browserresource.rst
===================================================================
--- bluebream/website/docs/v1.0/manual/browserresource.rst 2010-08-11 18:37:22 UTC (rev 115639)
+++ bluebream/website/docs/v1.0/manual/browserresource.rst 2010-08-12 02:32:34 UTC (rev 115640)
@@ -5,49 +5,50 @@
.. _man-browser-resource-file:
+Introduction
+------------
+
+Certain presentation, like images and style sheets are not associated with
+any other component, so that one cannot create a view. To solve this
+problem, resources were developed, which are presentation components that do
+not require any context. This chapter will demonstrate how resources are
+created and registered with BlueBream.
+
File Resource
-------------
-Certain presentation, like images and style sheets are not associated
-with any other component, so that one cannot create a view. To solve
-this problem, resources were developed, which are presentation
-components that do not require any context. This chapter will
-demonstrate how resources are created and registered with BlueBream.
-
The first goal is to register a simple plain-text file called
-``resource.txt`` as a browser resource. The first step is to create
-this file anywhere you wish on the filesystem, and adding the
-following content. If you are working on the official tutorial, you
-can create the file at: ``src/tc/main/resource.txt``::
+``resource.txt`` as a browser resource. The first step is to create this
+file anywhere you wish on the filesystem, and adding the following content.
+If you are working on the official tutorial, you can create the file at:
+``src/tc/main/resource.txt``::
Hello, I am a BlueBream Resource Component!
Now just register the resource in a ZCML configuration file using the
-browser resource directive. If you are working on the official
-tutorial, you can add these lines to ``src/tc/main/configure.zcml``::
+browser resource directive. If you are working on the official tutorial,
+you can add these lines to ``src/tc/main/configure.zcml``::
<browser:resource
name="resource.txt"
file="resource.txt"
layer="default" />
-- Line 2: This is the name under which the resource will be known in
- Zope.
+- Line 2: This is the name under which the resource will be known in Zope.
-- Line 3: The file attribute specifies the path to the resource on
- the filessytem. The current working directory (``.``) is always
- the directory the configuration file is located. So in the example
- above, the file ``resource.txt`` is located in the same folder as
- the configuration file is.
+- Line 3: The file attribute specifies the path to the resource on the
+ filessytem. The current working directory (``.``) is always the directory
+ the configuration file is located. So in the example above, the file
+ ``resource.txt`` is located in the same folder as the configuration file
+ is.
-- Line 4: The optional layer attribute specifies the layer the
- resource is added to. By default, the default layer is selected.
+- Line 4: The optional layer attribute specifies the layer the resource is
+ added to. By default, the default layer is selected.
-Once you hook up the configuration file to the main configuration
-path and restart BlueBream, you should be able to access the resource
-now via a Browser at: http://localhost:8080/@@/resource.txt. The
-``@@/`` in the URL tells the traversal mechanism that the following
-object is a resource.
+Once you hook up the configuration file to the main configuration path and
+restart BlueBream, you should be able to access the resource now via a
+Browser at: http://localhost:8080/@@/resource.txt. The ``@@/`` in the URL
+tells the traversal mechanism that the following object is a resource.
.. _man-browser-resource-image:
@@ -55,42 +56,39 @@
--------------
If you have an image resource, you might want to use different
-configuration. Create a simple image called ``img.png`` and register
-it as follows::
+configuration. Create a simple image called ``img.png`` and register it as
+follows::
<browser:resource
name="img.png"
image="img.png"
permission="zope.ManageContent" />
-- Line 3: As you can see, instead of the file attribute we use the
- image one. Internally this will create an Image object, which is
- able to detect the content type and returns it correctly. There is
- a third possible attribute named template. If specified, a Page
- Template that is executed when the resource is called. Note that
- only one of file, image, or template attributes can be specified
- inside a resource directive.
+- Line 3: As you can see, instead of the file attribute we use the image
+ one. Internally this will create an Image object, which is able to detect
+ the content type and returns it correctly. There is a third possible
+ attribute named template. If specified, a Page Template that is executed
+ when the resource is called. Note that only one of file, image, or
+ template attributes can be specified inside a resource directive.
-- Line 4: A final optional attribute is the ``permission`` one must
- have to view the resource. To demonstrate the security, I set the
- permission required for viewing the image to
- ``zope.ManageContent``, so that you must log in as an
- administrator/manager to be able to view it. The default of the
- attribute is ``zope.Public`` so that everyone can see the resource.
+- Line 4: A final optional attribute is the ``permission`` one must have to
+ view the resource. To demonstrate the security, I set the permission
+ required for viewing the image to ``zope.ManageContent``, so that you must
+ log in as an administrator/manager to be able to view it. The default of
+ the attribute is ``zope.Public`` so that everyone can see the resource.
.. _man-browser-resource-directory:
Directory Resource
------------------
-If you have many resource files to register, it can be very tedious
-to write a single directive for every resource. For this purpose the
-``browser:resourceDirectory`` directive is provided, with which you
-can simply declare an entire directory, including its content as
-resources. Thereby the filenames of the files are reused as the
-names for the resource available. Assuming you put your two previous
-resources in a directory called ``resource``, then you can use the
-following::
+If you have many resource files to register, it can be very tedious to write
+a single directive for every resource. For this purpose the
+``browser:resourceDirectory`` directive is provided, with which you can
+simply declare an entire directory, including its content as resources.
+Thereby the filenames of the files are reused as the names for the resource
+available. Assuming you put your two previous resources in a directory
+called ``resource``, then you can use the following::
<browser:resourceDirectory
name="resource"
@@ -100,18 +98,17 @@
The image will then be publically available from the following URL:
http://localhost:8080/@@/resources/img.png
-The directory resource object uses a simple resource type
-recognition. It looks at the filename extensions to discover the
-type. For page templates, currently the extensions ``pt``, ``zpt``
-and ``html`` are registered and for an image ``gif``, ``png`` and
-``jpg``. All other extensions are converted to file resources. Note
-that it is not necessary to have a list of all image types, since
-only Browser-displayable images must be recognized.
+The directory resource object uses a simple resource type recognition. It
+looks at the filename extensions to discover the type. For page templates,
+currently the extensions ``pt``, ``zpt`` and ``html`` are registered and for
+an image ``gif``, ``png`` and ``jpg``. All other extensions are converted
+to file resources. Note that it is not necessary to have a list of all
+image types, since only Browser-displayable images must be recognized.
-In BlueBream, there is a resource directory registered named
-``static``. If you are working the tutorial, you can see it at:
-``src/tc/main/configure.zcml``. At the beginning of the file, you
-can see the registration like this::
+In BlueBream, there is a resource directory registered named ``static``. If
+you are working the tutorial, you can see it at:
+``src/tc/main/configure.zcml``. At the beginning of the file, you can see
+the registration like this::
<browser:resourceDirectory
name="static"
@@ -122,16 +119,15 @@
available inside ``src/tc/main/static`` directory.
There is a community supported package named `z3c.zrtresource
-<http://pypi.python.org/pypi/z3c.zrtresource>`_ which provides a
-better way to register & use resources. For more information, look
-at the documentation: :ref:`commu-browser-resource`.
+<http://pypi.python.org/pypi/z3c.zrtresource>`_ which provides a better way
+to register & use resources. For more information, look at the
+documentation: :ref:`commu-browser-resource`.
.. raw:: html
<div id="disqus_thread"></div><script type="text/javascript"
src="http://disqus.com/forums/bluebream/embed.js"></script><noscript><a
- href="http://disqus.com/forums/bluebream/?url=ref">View the
- discussion thread.</a></noscript><a href="http://disqus.com"
- class="dsq-brlink">blog comments powered by <span
- class="logo-disqus">Disqus</span></a>
+ href="http://disqus.com/forums/bluebream/?url=ref">View the discussion
+ thread.</a></noscript><a href="http://disqus.com" class="dsq-brlink">blog
+ comments powered by <span class="logo-disqus">Disqus</span></a>
Modified: bluebream/website/docs/v1.0/manual/index.rst
===================================================================
--- bluebream/website/docs/v1.0/manual/index.rst 2010-08-11 18:37:22 UTC (rev 115639)
+++ bluebream/website/docs/v1.0/manual/index.rst 2010-08-12 02:32:34 UTC (rev 115640)
@@ -4,7 +4,6 @@
======
.. toctree::
- :numbered:
:maxdepth: 2
browserresource
Modified: bluebream/website/docs/v1.0/manual/interface.rst
===================================================================
--- bluebream/website/docs/v1.0/manual/interface.rst 2010-08-11 18:37:22 UTC (rev 115639)
+++ bluebream/website/docs/v1.0/manual/interface.rst 2010-08-12 02:32:34 UTC (rev 115640)
@@ -217,11 +217,11 @@
.. note::
- If you wonder how implements function works, refer the blog post by
+ If you wonder how ``implements`` function works, refer the blog post by
James Henstridge
- (http://blogs.gnome.org/jamesh/2005/09/08/python-class-advisors/)
- . In the adapter section, you will see an adapts function, it is
- also working similarly.
+ (http://blogs.gnome.org/jamesh/2005/09/08/python-class-advisors/) . In the
+ adapter section, you will see an ``adapts`` function, that is also working
+ similarly.
Since Host implements IHost, instances of Host provide IHost. There
are some utility methods to introspect the declarations. The
Modified: bluebream/website/docs/v1.0/manual/schema.rst
===================================================================
--- bluebream/website/docs/v1.0/manual/schema.rst 2010-08-11 18:37:22 UTC (rev 115639)
+++ bluebream/website/docs/v1.0/manual/schema.rst 2010-08-12 02:32:34 UTC (rev 115640)
@@ -9,16 +9,22 @@
Introduction
------------
-In the early stages of development, the BlueBream (then know as Zope
-3) developers decided that it would be cumbersome to manually write
-HTML forms and to manually validate the input. BlueBream team
-realized that if they could extend interfaces, we could auto-generate
-HTML forms and also automatically validate any input. This chapter
-gives some background information and formally introduces the
-``zope.schema`` and ``zope.formlib`` packages.
+In the early stages of development, the BlueBream (then know as Zope 3)
+developers decided that it would be cumbersome to manually write HTML forms
+and to manually validate the input. BlueBream team realized that if they
+could extend interfaces, we could auto-generate HTML forms and also
+automatically validate any input. This chapter gives some background
+information and formally introduces the ``zope.schema`` and ``zope.formlib``
+packages.
-Schema is an interface defined using special attributes called
-``fields``.
+Schema is an interface defined using special attributes called ``fields``.
+Schemas extend the notion of interfaces to detailed descriptions of
+Attributes (but not methods). Every schema is an interface and specifies
+the public fields of an object. A *field* roughly corresponds to an
+attribute of a python object. But a Field provides space for at least a
+title and a description. It can also constrain its value and provide a
+validation method. Besides you can optionally specify characteristics such
+as its value being read-only or not required.
The schema was developed based on the following three main goals:
@@ -28,19 +34,31 @@
3. Automated GUI form generation (mainly for the Web browser)
+BlueBream schemas were born when Jim Fulton and Martijn Faassen thought
+about Formulator for Zope 3 and ``PropertySets`` while at the `Zope 3 sprint
+<http://wiki.zope.org/zope3/ZopeBBQ2002Sprint>`_ at the Zope BBQ in Berlin.
+They realized that if you strip all view logic from forms then you have
+something similar to interfaces. And thus schemas were born.
+The implementation of Schema resides in `zope.schema` package. The
+`zope.schema` package is intended to be independently reusable in any Python
+project. Like many other packages in BlueBream, the zope.schema is also
+maintained by the `Zope Toolkit project
+<http://docs.zope.org/zopetoolkit/>`_.
+
+
Schema versus Interfaces
------------------------
As mentioned before, schemas are just an extension to interfaces and
-therefore depend on the *zope.interface* package. Fields in schemas
-are equivalent to methods in interfaces. Both are complementary to
-each other, since they describe different aspects of an object. The
-methods of an interface describe the functionality of a component,
-while the schema's fields represent the state.
+therefore depend on the *zope.interface* package. Fields in schemas are
+equivalent to methods in interfaces. Both are complementary to each other,
+since they describe different aspects of an object. The methods of an
+interface describe the functionality of a component, while the schema's
+fields represent the state.
-It is thus not necessary to develop a new syntax for writing schemas
-so, schema simply reuse the interface declaration.
+It is thus not necessary to develop a new syntax for writing schemas so,
+schema simply reuse the interface declaration.
::
@@ -54,119 +72,340 @@
description=u"The text of the example.",
required=True)
-- Line 2: All default fields can be simply imported from
- ``zope.schema``.
+- Line 2: All default fields can be simply imported from ``zope.schema``.
-- Line 7-8: The title and description are used as human-readable text
- for the form generation. Of course, they also serve as
- documentation of the field itself.
+- Line 7-8: The title and description are used as human-readable text for
+ the form generation. Of course, they also serve as documentation of the
+ field itself.
- Line 9: Various fields support several other meta-data fields. The
- required option is actually available for all fields and specifies
- whether an object implementing IExample must provide a value for
- text or not.
+ required option is actually available for all fields and specifies whether
+ an object implementing IExample must provide a value for text or not.
+Simple Usage
+------------
+
+Let's have a look at a simple example. First we write an interface as usual,
+but instead of describing the attributes of the interface with ``Attribute``
+instances, we now use schema fields:
+
+ >>> import zope.interface
+ >>> import zope.schema
+
+ >>> class IBookmark(zope.interface.Interface):
+ ... title = zope.schema.TextLine(
+ ... title=u'Title',
+ ... description=u'The title of the bookmark',
+ ... required=True)
+ ...
+ ... url = zope.schema.URI(
+ ... title=u'Bookmark URL',
+ ... description=u'URL of the Bookmark',
+ ... required=True)
+ ...
+
+Now we create a class that implements this interface and create an instance
+of it:
+
+ >>> class Bookmark(object):
+ ... zope.interface.implements(IBookmark)
+ ...
+ ... title = None
+ ... url = None
+
+ >>> bm = Bookmark()
+
+We would now like to only add validated values to the class. This can be
+done by first validating and then setting the value on the object. The
+first step is to define some data:
+
+ >>> title = u'BlueBream Website'
+ >>> url = 'http://bluebream.zope.org'
+
+Now we, get the fields from the interface:
+
+ >>> title_field = IBookmark.get('title')
+ >>> url_field = IBookmark.get('url')
+
+Next we have to bind these fields to the context, so that instance-specific
+information can be used for validation:
+
+ >>> title_bound = title_field.bind(bm)
+ >>> url_bound = url_field.bind(bm)
+
+Now that the fields are bound, we can finally validate the data:
+
+ >>> title_bound.validate(title)
+ >>> url_bound.validate(url)
+
+If the validation is successful, ``None`` is returned. If a validation error
+occurs a ``ValidationError`` will be raised; for example:
+
+ >>> url_bound.validate(u'http://zope.org/foo')
+ Traceback (most recent call last):
+ ...
+ WrongType: (u'http://zope.org/foo', <type 'str'>, 'url')
+
+ >>> url_bound.validate('foo.bar')
+ Traceback (most recent call last):
+ ...
+ InvalidURI: foo.bar
+
+Now that the data has been successfully validated, we can set it on the
+object:
+
+ >>> title_bound.set(bm, title)
+ >>> url_bound.set(bm, url)
+
+That's it. You still might think this is a lot of work to validate and set
+a value for an object. Note, however, that it is very easy to write helper
+functions that automate these tasks. If correctly designed, you will never
+have to worry explicitly about validation again, since the system takes care
+of it automatically.
+
+
+What is a schema, how does it compare to an interface?
+------------------------------------------------------
+
+A schema is an extended interface which defines fields. You can validate
+that the attributes of an object conform to their fields defined on the
+schema. With plain interfaces you can only validate that methods conform to
+their interface specification.
+
+So interfaces and schemas refer to different aspects of an object
+(respectively its code and state).
+
+A schema starts out like an interface but defines certain fields to which an
+object's attributes must conform. Let's look at a stripped down example
+from the programmer's tutorial:
+
+ >>> import re
+
+ >>> class IContact(zope.interface.Interface):
+ ... """Provides access to basic contact information."""
+ ...
+ ... first = zope.schema.TextLine(title=u"First name")
+ ...
+ ... last = zope.schema.TextLine(title=u"Last name")
+ ...
+ ... email = zope.schema.TextLine(title=u"Electronic mail address")
+ ...
+ ... address = zope.schema.Text(title=u"Postal address")
+ ...
+ ... postalCode = zope.schema.TextLine(
+ ... title=u"Postal code",
+ ... constraint=re.compile("\d{5,5}(-\d{4,4})?$").match)
+
+``TextLine`` is a field and expresses that an attribute is a single line of
+Unicode text. ``Text`` expresses an arbitrary Unicode ("text") object. The
+most interesting part is the last attribute specification. It constrains
+the ``postalCode`` attribute to only have values that are US postal codes.
+
+Now we want a class that adheres to the ``IContact`` schema:
+
+ >>> class Contact(object):
+ ... zope.interface.implements(IContact)
+ ...
+ ... def __init__(self, first, last, email, address, pc):
+ ... self.first = first
+ ... self.last = last
+ ... self.email = email
+ ... self.address = address
+ ... self.postalCode = pc
+
+Now you can see if an instance of ``Contact`` actually implements the
+schema:
+
+ >>> someone = Contact(u'Tim', u'Roberts', u'tim at roberts', u'',
+ ... u'12032-3492')
+
+ >>> for field in zope.schema.getFields(IContact).values():
+ ... bound = field.bind(someone)
+ ... bound.validate(bound.get(someone))
+
+
+Data Modeling Concepts
+-----------------------
+
+The ``zope.schema`` package provides a core set of field types, including
+single- and multi-line text fields, binary data fields, integers,
+floating-point numbers, and date/time values.
+
+Selection issues; field type can specify:
+
+- "Raw" data value
+
+ Simple values not constrained by a selection list.
+
+- Value from enumeration (options provided by schema)
+
+ This models a single selection from a list of possible values specified by
+ the schema. The selection list is expected to be the same for all values
+ of the type. Changes to the list are driven by schema evolution.
+
+ This is done by mixing-in the ``IEnumerated`` interface into the field
+ type, and the Enumerated mix-in for the implementation (or emulating it in
+ a concrete class).
+
+- Value from selection list (options provided by an object)
+
+ This models a single selection from a list of possible values specified by
+ a source outside the schema. The selection list depends entirely on the
+ source of the list, and may vary over time and from object to object.
+ Changes to the list are not related to the schema, but changing how the
+ list is determined is based on schema evolution.
+
+ There is not currently a spelling of this, but it could be facilitated
+ using alternate mix-ins similar to IEnumerated and Enumerated.
+
+- Whether or not the field is read-only
+
+ If a field value is read-only, it cannot be changed once the object is
+ created.
+
+- Whether or not the field is required
+
+ If a field is designated as required, assigned field values must always be
+ non-missing. See the next section for a description of missing values.
+
+- A value designated as ``missing``
+
+ Missing values, when assigned to an object, indicate that there is 'no
+ data' for that field. Missing values are analogous to null values in
+ relational databases. For example, a boolean value can be True, False, or
+ missing, in which case its value is unknown.
+
+ While Python's None is the most likely value to signify 'missing', some
+ fields may use different values. For example, it is common for text
+ fields to use the empty string ('') to signify that a value is missing.
+ Numeric fields may use 0 or -1 instead of None as their missing value.
+
+ A field that is 'required' signifies that missing values are invalid and
+ should not be assigned.
+
+- A default value
+
+ Default field values are assigned to objects when they are first created.
+
+
+Fields and Widgets
+------------------
+
+Widgets are components that display field values and, in the case of
+writable fields, allow the user to edit those values.
+
+Widgets:
+
+- Display current field values, either in a read-only format, or in a
+ format that lets the user change the field value.
+
+- Update their corresponding field values based on values provided by users.
+
+- Manage the relationships between their representation of a field value and
+ the object's field value. For example, a widget responsible for editing a
+ number will likely represent that number internally as a string. For this
+ reason, widgets must be able to convert between the two value formats. In
+ the case of the number-editing widget, string values typed by the user
+ need to be converted to numbers such as int or float.
+
+- Support the ability to assign a missing value to a field. For example, a
+ widget may present a ``None`` option for selection that, when selected,
+ indicates that the object should be updated with the field's ``missing``
+ value.
+
Core Schema Fields
------------------
-After we have seen a simple example of a schema, let's now look at
-all the basic fields and their properties.
+After we have seen a simple example of a schema, let's now look at all the
+basic fields and their properties.
- Properties that all fields support:
- - ``title`` (type: *TextLine*): The title of the attribute is used
- as label when displaying the field widget.
+ - ``title`` (type: *TextLine*): The title of the attribute is used as
+ label when displaying the field widget.
- - ``description`` (type: *Text*): The description of the attribute
- is used for tooltips and advanced help.
+ - ``description`` (type: *Text*): The description of the attribute is used
+ for tooltips and advanced help.
- - ``required`` (type: *Bool*): Specifies whether an attribute is
- required or not to have a value. In add-forms, required
- attributes are equivalent to required constructor arguments.
+ - ``required`` (type: *Bool*): Specifies whether an attribute is required
+ or not to have a value. In add-forms, required attributes are
+ equivalent to required constructor arguments.
- - ``readonly`` (type: *Bool*): If a field is readonly, then the
- value of the attribute can be set only once and can then only be
- displayed. Often a unique id for some object is a good candidate
- for a read-only field.
+ - ``readonly`` (type: *Bool*): If a field is readonly, then the value of
+ the attribute can be set only once and can then only be displayed.
+ Often a unique id for some object is a good candidate for a read-only
+ field.
- - ``default`` (type: depends on field): The default value that is
- given to the attribute, if no initialization value was provided.
- This value is often specified, if a field is required.
+ - ``default`` (type: depends on field): The default value that is given to
+ the attribute, if no initialization value was provided. This value is
+ often specified, if a field is required.
- - ``order`` (type: *Int*): Fields are often grouped by some logical
- order. This value specifies a relative position in this order.
- We usually do not set this value manually, since it is
- automatically assigned when an interface is initialized. The
- order of the fields in a schema is by default the same as the
- order of the fields in the Python code.
+ - ``order`` (type: *Int*): Fields are often grouped by some logical order.
+ This value specifies a relative position in this order. We usually do
+ not set this value manually, since it is automatically assigned when an
+ interface is initialized. The order of the fields in a schema is by
+ default the same as the order of the fields in the Python code.
- Bytes, BytesLine
- Bytes and BytesLine only differ by the fact that BytesLine cannot
- contain a new line character. Bytes behave identical to the Python
- type str.
+ Bytes and BytesLine only differ by the fact that BytesLine cannot contain
+ a new line character. Bytes behave identical to the Python type str.
Bytes and BytesLine fields are iteratable.
- - ``min_length`` (type: *Int*): After the white space has been
- normalized, there cannot be less than this amount of characters
- in the bytes string. The default is None, which refers to no
- minimum.
+ - ``min_length`` (type: *Int*): After the white space has been normalized,
+ there cannot be less than this amount of characters in the bytes string.
+ The default is None, which refers to no minimum.
- - ``max_length`` (type: *Int*): After the white space has been
- normalized, there cannot be more than this amount of characters
- in the bytes string. The default is None, which refers to no
- maximum.
+ - ``max_length`` (type: *Int*): After the white space has been normalized,
+ there cannot be more than this amount of characters in the bytes string.
+ The default is None, which refers to no maximum.
- Text, TextLine
- The two fields only differ by the fact that TextLine cannot contain
- a newline character. Text fields contain unicode, meaning that
- they are intended to be human-readable strings/text.
+ The two fields only differ by the fact that TextLine cannot contain a
+ newline character. Text fields contain unicode, meaning that they are
+ intended to be human-readable strings/text.
Text and TextLine fields are iteratable.
- - ``min_length`` (type: *Int*): After the white space has been
- normalized, there cannot be less than this amount of characters
- in the text string. The default is None, which refers to no
- minimum.
+ - ``min_length`` (type: *Int*): After the white space has been normalized,
+ there cannot be less than this amount of characters in the text string.
+ The default is None, which refers to no minimum.
- - ``max_length`` (type: *Int*): After the white space has been
- normalized, there cannot be more than this amount of characters
- in the text string. The default is None, which refers to no
- maximum.
+ - ``max_length`` (type: *Int*): After the white space has been normalized,
+ there cannot be more than this amount of characters in the text string.
+ The default is None, which refers to no maximum.
- SourceText
- Source Text is a special field derived from Text, which contains
- source code of any type. It is more or less a marker field for the
- forms machinery, so that special input fields can be used for
- source code.
+ Source Text is a special field derived from Text, which contains source
+ code of any type. It is more or less a marker field for the forms
+ machinery, so that special input fields can be used for source code.
- Password
- Password is a special derivative for the TextLine field and is
- treated separately for presentation reasons. However, someone also
- might want more fine-grained validation for passwords.
+ Password is a special derivative for the TextLine field and is treated
+ separately for presentation reasons. However, someone also might want
+ more fine-grained validation for passwords.
- Bool
- The Bool field has no further attributes. It maps directly to
- Python's bool object.
+ The Bool field has no further attributes. It maps directly to Python's
+ bool object.
- Int
Int fields directly map to Python's int type.
- - ``min`` (type: *Int*): Specifies the smallest acceptable integer.
- This is useful in many ways, such as allowing only positive
- values by making this field 0.
+ - ``min`` (type: *Int*): Specifies the smallest acceptable integer. This
+ is useful in many ways, such as allowing only positive values by making
+ this field 0.
- - ``max`` (type: *Int*): Specifies the largest acceptable integer,
- which excludes the value itself. It can be used to specify an
- upper bound, such as the current year, if you are interested in
- the past only.
+ - ``max`` (type: *Int*): Specifies the largest acceptable integer, which
+ excludes the value itself. It can be used to specify an upper bound,
+ such as the current year, if you are interested in the past only.
Both attributes combined allow the programmer to specify ranges of
acceptable values.
@@ -175,292 +414,278 @@
Float fields directly map to Python's float type.
- - ``min`` (type: *Float*): Specifies the smallest acceptable
- floating point number. This is useful in many ways, such as
- allowing only positive values by making this field 0.0.
+ - ``min`` (type: *Float*): Specifies the smallest acceptable floating
+ point number. This is useful in many ways, such as allowing only
+ positive values by making this field 0.0.
- - ``max`` (type: *Float*): Specifies the largest acceptable
- floating point number, which excludes the value itself (typical
- computer programming pattern). It can be used to specify an
- upper bound, such as 1.0, if you are only interested in
- probabilities.
+ - ``max`` (type: *Float*): Specifies the largest acceptable floating point
+ number, which excludes the value itself (typical computer programming
+ pattern). It can be used to specify an upper bound, such as 1.0, if you
+ are only interested in probabilities.
Both attributes combined allow the programmer to specify ranges of
acceptable values.
- Datetime
- Similar to Int and Float, Datetime has a min and max field that
- specify the boundaries of the possible values. Acceptable values
- for these fields must be instances of the builtin datetime type.
+ Similar to Int and Float, Datetime has a min and max field that specify
+ the boundaries of the possible values. Acceptable values for these fields
+ must be instances of the builtin datetime type.
- Tuple, List
- The reason both of these fields exists is that we can easily map
- them to their Python type tuple and list, respectively.
+ The reason both of these fields exists is that we can easily map them to
+ their Python type tuple and list, respectively.
Tuple and List fields are iteratable.
- - ``min_length`` (type: *Int*): There cannot be less than this
- amount of items in the sequence. The default is None, which
- means there is no minimum.
+ - ``min_length`` (type: *Int*): There cannot be less than this amount of
+ items in the sequence. The default is None, which means there is no
+ minimum.
- - ``max_length`` (type: *Int*): There cannot be more than this
- amount of items in the sequence. The default is None, which
- means there is no maximum.
+ - ``max_length`` (type: *Int*): There cannot be more than this amount of
+ items in the sequence. The default is None, which means there is no
+ maximum.
- - ``value_type`` (type: *Field*): Values contained by these
- sequence types must conform to this field's constraint. Most
- commonly a Choice field (see below) is specified here, which
- allows you to select from a fixed set of values.
+ - ``value_type`` (type: *Field*): Values contained by these sequence types
+ must conform to this field's constraint. Most commonly a Choice field
+ (see below) is specified here, which allows you to select from a fixed
+ set of values.
- Dict
- The Dict is a mapping field that maps from one set of fields to
- another.
+ The Dict is a mapping field that maps from one set of fields to another.
fields are iteratable.
- - ``min_length`` (type: *Int*): There cannot be less than this
- amount of items in the dictionary. The default is None, which
- means there is no minimum.
+ - ``min_length`` (type: *Int*): There cannot be less than this amount of
+ items in the dictionary. The default is None, which means there is no
+ minimum.
- - ``max_length`` (type: *Int*): There cannot be more than this
- amount of items in the dictionary. The default is None, which
- means there is no maximum.
+ - ``max_length`` (type: *Int*): There cannot be more than this amount of
+ items in the dictionary. The default is None, which means there is no
+ maximum.
- - ``key_type`` (type: *Field*): Every dictionary item key has to
+ - ``key_type`` (type: *Field*): Every dictionary item key has to conform
+ to the specified field.
+
+ - ``value_type`` (type: *Field*): Every dictionary item value has to
conform to the specified field.
- - ``value_type`` (type: *Field*): Every dictionary item value has
- to conform to the specified field.
-
- Choice
- The Choice field allows one to select a particular value from a
- provided set of values. You can either provide the values as a
- simple sequence (list or tuple) or specify a vocabulary (by
- reference or name) that will provide the values. Vocabularies
- provide a flexible list of values, in other words the set of
- allowed values can change as the system changes. Since they are so
- complex, they are covered separately in "Vocabularies and Fields".
+ The Choice field allows one to select a particular value from a provided
+ set of values. You can either provide the values as a simple sequence
+ (list or tuple) or specify a vocabulary (by reference or name) that will
+ provide the values. Vocabularies provide a flexible list of values, in
+ other words the set of allowed values can change as the system changes.
+ Since they are so complex, they are covered separately in "Vocabularies
+ and Fields".
- - ``vocabulary`` (type: *Vocabulary*): A vocabulary instance that
- is used to provide the available values. This attribute is None,
- if a vocabulary name was specified and the field has not been
- bound to a context.
+ - ``vocabulary`` (type: *Vocabulary*): A vocabulary instance that is used
+ to provide the available values. This attribute is None, if a
+ vocabulary name was specified and the field has not been bound to a
+ context.
- - ``vocabularyName`` (type: *TextLine*): The name of the vocabulary
- that is used to provide the values. The vocabulary for this name
- can only be looked up, when the field is bound, in other words
- has a context. Upon binding, the vocabulary is automatically
- looked using the name and the context.
+ - ``vocabularyName`` (type: *TextLine*): The name of the vocabulary that
+ is used to provide the values. The vocabulary for this name can only be
+ looked up, when the field is bound, in other words has a context. Upon
+ binding, the vocabulary is automatically looked using the name and the
+ context.
- The constructor also accepts a values argument that specifies a
- static set of values. These values are immediately converted to a
- static vocabulary.
+ The constructor also accepts a values argument that specifies a static set
+ of values. These values are immediately converted to a static vocabulary.
- Object
- This field specifies an object that must implement a specific
- schema. Only objects that provide the specified schema are
- allowed.
+ This field specifies an object that must implement a specific schema.
+ Only objects that provide the specified schema are allowed.
- - ``schema`` (type: *Interface*): This field provides a reference
- to the schema that must be provided by objects that want to be
- stored in the described attribute.
+ - ``schema`` (type: *Interface*): This field provides a reference to the
+ schema that must be provided by objects that want to be stored in the
+ described attribute.
- DottedName
- Derived from the BytesLine field, the DottedName field represents
- valid Python-style dotted names (object references). This field
- can be used when it is desirable that a valid and resolvable Python
- dotted name is provided.
+ Derived from the BytesLine field, the DottedName field represents valid
+ Python-style dotted names (object references). This field can be used
+ when it is desirable that a valid and resolvable Python dotted name is
+ provided.
This field has no further attributes.
- URI
- Derived from the BytesLine field, the URI field makes sure that the
- value is always a valid URI. This is particularly useful when you
- want to reference resources (such as RSS feeds or images) on remote
- computers.
+ Derived from the BytesLine field, the URI field makes sure that the value
+ is always a valid URI. This is particularly useful when you want to
+ reference resources (such as RSS feeds or images) on remote computers.
This field has no further attributes.
- Id
- Both, the DottedName and URI field, make up the Id field. Any
- dotted name or URI represent a valid id in Zope. Ids are used for
- identifying many types of objects, such as permissions and
- principals, but also for providing annotation keys.
+ Both, the DottedName and URI field, make up the Id field. Any dotted name
+ or URI represent a valid id in Zope. Ids are used for identifying many
+ types of objects, such as permissions and principals, but also for
+ providing annotation keys.
This field has no further attributes.
- InterfaceField
- The Interface field has no further attributes. Its value must be
- an object that provides zope.interface.Interface, in other words it
- must be an interface.
+ The Interface field has no further attributes. Its value must be an
+ object that provides zope.interface.Interface, in other words it must be
+ an interface.
-For a formal listing of the Schema/Field API, see the API
-documentation tool at `http://localhost:8080/++apidoc++`_ or see
-zope.schema.interfaces module.
+For a formal listing of the Schema/Field API, see the API documentation tool
+at `http://localhost:8080/++apidoc++`_ or see zope.schema.interfaces module.
Auto-generated Forms using the forms Package
--------------------------------------------
-Forms are much more BlueBream specific than schemas and can be found
-in the ``zope.formlib`` package. The views of schema fields are
-called widgets. Widgets responsible for data display and conversion
-in their specific presentation type. Currently widgets exist mainly
-for HTML (the Web browser).
+Forms are much more BlueBream specific than schemas and can be found in the
+``zope.formlib`` package. The views of schema fields are called widgets.
+Widgets responsible for data display and conversion in their specific
+presentation type. Currently widgets exist mainly for HTML (the Web
+browser).
-Widgets are separated into two groups, display and input widgets.
-Display widgets are often very simply and only show a text
-representation of the Python object. The input widgets, however, are
-more complex and display a greater variety of choices. The following
-list shows all available browser- based input widgets (found in
-zope.formlib.widget):
+Widgets are separated into two groups, display and input widgets. Display
+widgets are often very simply and only show a text representation of the
+Python object. The input widgets, however, are more complex and display a
+greater variety of choices. The following list shows all available browser-
+based input widgets (found in zope.formlib.widget):
Text Widgets
~~~~~~~~~~~~
-Text-based widgets always require some sort of keyboard input. A
-string representation of a field is then converted to the desired
-Python object, like and integer or a date.
+Text-based widgets always require some sort of keyboard input. A string
+representation of a field is then converted to the desired Python object,
+like and integer or a date.
-- ``TextWidget``: Being probably the simplest widget, it displays the
- text input element and is mainly used for the ``TextLine``, which
- expects to be unicode. It also serves as base widget for many of
- the following widgets.
+- ``TextWidget``: Being probably the simplest widget, it displays the text
+ input element and is mainly used for the ``TextLine``, which expects to be
+ unicode. It also serves as base widget for many of the following widgets.
-- ``TextAreaWidget``: As the name suggests this widget displays a
- text area and assumes its input to be some unicode string. (note
- that the Publisher already takes care of the encoding issues).
+- ``TextAreaWidget``: As the name suggests this widget displays a text area
+ and assumes its input to be some unicode string. (note that the Publisher
+ already takes care of the encoding issues).
- ``BytesWidget``, ``BytesAreaWidget``: Direct descendents from
- ``TextWidget`` and ``TextAreaWidget``, the only difference is that
- these widgets expect bytes as input and not a unicode string, which
- means they must be valid ASCII encodable.
+ ``TextWidget`` and ``TextAreaWidget``, the only difference is that these
+ widgets expect bytes as input and not a unicode string, which means they
+ must be valid ASCII encodable.
-- ``ASCIIWidget``: This widget, based on the ``BytesWidget``, ensures
- that only ASCII character are part of the inputted data.
+- ``ASCIIWidget``: This widget, based on the ``BytesWidget``, ensures that
+ only ASCII character are part of the inputted data.
- ``PasswordWidget``: Almost identical to the ``TextWidget``, it only
displays a password element instead of a text element.
-- ``IntWidget``: A derivative of ``TextWidget``, it only overwrites
- the conversion method to ensure the conversion to an integer.
+- ``IntWidget``: A derivative of ``TextWidget``, it only overwrites the
+ conversion method to ensure the conversion to an integer.
-- ``FloatWidget``: Derivative of ``TextWidget``, it only overwrites
- the conversion method to ensure the conversion to an floating
- point.
+- ``FloatWidget``: Derivative of ``TextWidget``, it only overwrites the
+ conversion method to ensure the conversion to an floating point.
-- ``DatetimeWidget``: Someone might expect a smart and complex widget
- at this point, but for now it is just a simple ``TextWidget`` with
- a string to datetime converter. There is also a ``DateWidget``
- that only handles dates.
+- ``DatetimeWidget``: Someone might expect a smart and complex widget at
+ this point, but for now it is just a simple ``TextWidget`` with a string
+ to datetime converter. There is also a ``DateWidget`` that only handles
+ dates.
Boolean Widgets
~~~~~~~~~~~~~~~
-Boolean widgets' only responsibility is to convert some binary input
-to the Python values *True* or *False*.
+Boolean widgets' only responsibility is to convert some binary input to the
+Python values *True* or *False*.
-- ``CheckBoxWidget``: This widget displays a single checkbox widget
- that can be either checked or unchecked, representing the state of
- the boolean value.
+- ``CheckBoxWidget``: This widget displays a single checkbox widget that can
+ be either checked or unchecked, representing the state of the boolean
+ value.
-- ``BooleanRadioWidget``: Two radio buttons are used to represent the
- true and false state of the boolean. One can pass the textual
- value for the two states in the constructor. The default is *on*
- and *off* (or their translation for languages other than English).
+- ``BooleanRadioWidget``: Two radio buttons are used to represent the true
+ and false state of the boolean. One can pass the textual value for the
+ two states in the constructor. The default is *on* and *off* (or their
+ translation for languages other than English).
- ``BooleanSelectWidget``, ``BooleanDropdownWidget``: Similar to the
- ``BooleanRadioWidget``, textual representations of the true and
- false state are used to select the value. See ``SelectWidget`` and
+ ``BooleanRadioWidget``, textual representations of the true and false
+ state are used to select the value. See ``SelectWidget`` and
``DropdownWidget``, respectively, for more details.
Single Selection Widgets
~~~~~~~~~~~~~~~~~~~~~~~~
-Widgets that allow a single item to be selected from a list of values
-are usually views of a field, a vocabulary and the request, instead
-of just the field and request pair. Therefore so called
-proxy-widgets are used to map from field-request to
-field-vocabulary-request pairs. For example the
-``ChoiceInputWidget``, which takes a Choice field and a request
-object, is simply a function that looks up another widget that is
-registered for the Choice field, its vocabulary and the request.
-Below is a list of all available widgets that require the latter
-three inputs.
+Widgets that allow a single item to be selected from a list of values are
+usually views of a field, a vocabulary and the request, instead of just the
+field and request pair. Therefore so called proxy-widgets are used to map
+from field-request to field-vocabulary-request pairs. For example the
+``ChoiceInputWidget``, which takes a Choice field and a request object, is
+simply a function that looks up another widget that is registered for the
+Choice field, its vocabulary and the request. Below is a list of all
+available widgets that require the latter three inputs.
-- ``SelectWidget``: This widget provides a multiply-sized selection
- element where the options are populated through the vocabulary
- terms. If the field is not required, a "no value" option will be
- available as well. The user will allowed to only select one value
- though, since the ``Choice`` field is not a sequence-based field.
+- ``SelectWidget``: This widget provides a multiply-sized selection element
+ where the options are populated through the vocabulary terms. If the
+ field is not required, a "no value" option will be available as well. The
+ user will allowed to only select one value though, since the ``Choice``
+ field is not a sequence-based field.
-- ``DropdownWidget``: As a simple derivative of the ``SelectWdiget``,
- it has its size set to "1", which makes it a dropdown box.
- Dropdown boxes have the advantage that they always just show one
- value, which makes some more user-friendly for single selections.
+- ``DropdownWidget``: As a simple derivative of the ``SelectWdiget``, it has
+ its size set to "1", which makes it a dropdown box. Dropdown boxes have
+ the advantage that they always just show one value, which makes some more
+ user-friendly for single selections.
-- ``RadioWidget``: This widget displays a radio button for each term
- in the vocabulary. Radio buttons have the advantage that they
- always show all choices and are therefore well suitable for small
- vocabularies.
+- ``RadioWidget``: This widget displays a radio button for each term in the
+ vocabulary. Radio buttons have the advantage that they always show all
+ choices and are therefore well suitable for small vocabularies.
Multiple Selections Widgets
~~~~~~~~~~~~~~~~~~~~~~~~~~~
This group of widgets is used to display input forms collection-based
-fields, such as List or Set. Similar to the single selection
-widgets, two proxy- widgets are used to look up the correct widget.
-The first step is to map from field- request to field- value_type-
-request using a widget called ``CollectionInputWidget``. This allows
-us to use different widgets when the value type is an Int or Choice
-field for example. Optionally, a second proxy-widget is used to
-convert the field- value_type- request pair to a field- vocabulary-
-request pair, as it is the case when the value type is a choice
-field.
+fields, such as List or Set. Similar to the single selection widgets, two
+proxy- widgets are used to look up the correct widget. The first step is to
+map from field- request to field- value_type- request using a widget called
+``CollectionInputWidget``. This allows us to use different widgets when the
+value type is an Int or Choice field for example. Optionally, a second
+proxy-widget is used to convert the field- value_type- request pair to a
+field- vocabulary- request pair, as it is the case when the value type is a
+choice field.
- ``MultiSelectWidget``: Creates a select element with the multiple
- attribute set to true. This creates a multi-selection box. This
- is especially useful for vocabularies with many terms. Note that
- if your vocabulary supports a query interface, you can even filter
- your selectable items using queries.
+ attribute set to true. This creates a multi-selection box. This is
+ especially useful for vocabularies with many terms. Note that if your
+ vocabulary supports a query interface, you can even filter your selectable
+ items using queries.
-- ``MultiCheckBoxWidget``: Similar to the multi-selection widget,
- this widget allows multi-value selections of a given list, but uses
- checkboxes instead of a list. This widget is more useful for
- smaller vocabularies.
+- ``MultiCheckBoxWidget``: Similar to the multi-selection widget, this
+ widget allows multi-value selections of a given list, but uses checkboxes
+ instead of a list. This widget is more useful for smaller vocabularies.
-- ``TupleSequenceWidget``: This widget is used for all cases where
- the value type is not a Choice field. It used the widget of the
- value type field to add new values to the tuple. Other input
- elements are used to remove items.
+- ``TupleSequenceWidget``: This widget is used for all cases where the value
+ type is not a Choice field. It used the widget of the value type field to
+ add new values to the tuple. Other input elements are used to remove
+ items.
-- ``ListSequenceWidget``: This widget is equivalent to the previous
- one, except that it generates lists instead of tuples.
+- ``ListSequenceWidget``: This widget is equivalent to the previous one,
+ except that it generates lists instead of tuples.
Miscellaneous Widgets
~~~~~~~~~~~~~~~~~~~~~
-- ``FileWidget``: This widget displays a file input element and makes
- sure the received data is a file. This field is ideal for quickly
- uploading byte streams as required for the ``Bytes`` field.
+- ``FileWidget``: This widget displays a file input element and makes sure
+ the received data is a file. This field is ideal for quickly uploading
+ byte streams as required for the ``Bytes`` field.
-- ``ObjectWidget``: The ``ObjectWidget`` is the view for an object
- field. It uses the schema of the object to construct an input
- form. The object factory, which is passed in as a constructor
- argument, is used to build the object from the input afterwards.
+- ``ObjectWidget``: The ``ObjectWidget`` is the view for an object field.
+ It uses the schema of the object to construct an input form. The object
+ factory, which is passed in as a constructor argument, is used to build
+ the object from the input afterwards.
Here is a simple interactive example demonstrating the rendering and
conversion functionality of a widget::
@@ -486,46 +711,45 @@
/>
-- Line 1 & 5: For views, including widgets, we always need a request
- object. The ``TestRequest`` class is the quick and easy way to
- create a request without much hassle. For each presentation type
- there exists a TestRequest class. The class takes a form argument,
- which is a dictionary of values contained in the HTML form. The
- widget will later access this information.
+- Line 1 & 5: For views, including widgets, we always need a request object.
+ The ``TestRequest`` class is the quick and easy way to create a request
+ without much hassle. For each presentation type there exists a
+ TestRequest class. The class takes a form argument, which is a dictionary
+ of values contained in the HTML form. The widget will later access this
+ information.
- Line 2: Import an integer field.
-- Line 3 & 6: Import the widget that displays and converts an integer
- from the HTML form. Initializing a widget only requires a field
- and a request.
+- Line 3 & 6: Import the widget that displays and converts an integer from
+ the HTML form. Initializing a widget only requires a field and a request.
-- Line 4: Create an integer field with the constraint that the value
- must lie between 0 and 10. The __name__ argument must be passed
- here, since the field has not been initialized inside an interface,
- where the __name__ would be automatically assigned.
+- Line 4: Create an integer field with the constraint that the value must
+ lie between 0 and 10. The __name__ argument must be passed here, since
+ the field has not been initialized inside an interface, where the __name__
+ would be automatically assigned.
-- Line 7-8: This method checks whether the form contained a value for
- this widget.
+- Line 7-8: This method checks whether the form contained a value for this
+ widget.
-- Line 9-10: If so, then we can use the ``getInputValue()`` method to
- return the converted and validated value (an integer in this case).
- If we would have chosen an integer outside this range, a
- WidgetInputError would have been raised.
+- Line 9-10: If so, then we can use the ``getInputValue()`` method to return
+ the converted and validated value (an integer in this case). If we would
+ have chosen an integer outside this range, a WidgetInputError would have
+ been raised.
- Line 11-20: Display the HTML representation of the widget. The
``replace()`` call is only for better readability of the output.
Note that you usually will not have to deal with these methods at all
-manually, since the form generator and data converter does all the
-work for you. The only method you will commonly overwrite is
-``_validate()``, which you will use to validate custom values. This
-brings us right into the next subject, customizing widgets.
+manually, since the form generator and data converter does all the work for
+you. The only method you will commonly overwrite is ``_validate()``, which
+you will use to validate custom values. This brings us right into the next
+subject, customizing widgets.
-There are two ways of customizing widgets. For small adjustments to
-some parameters (properties of the widget), one can use the
-browser:widget subdirective of the browser:addform and
-browser:editform directives. For example, to change the widget for a
-field called "name", the following ZCML code can be used.
+There are two ways of customizing widgets. For small adjustments to some
+parameters (properties of the widget), one can use the browser:widget
+subdirective of the browser:addform and browser:editform directives. For
+example, to change the widget for a field called "name", the following ZCML
+code can be used.
::
@@ -540,14 +764,13 @@
</browser:addform>
-In this case we force the system to use the ``TextWidget`` for the
-name, set the display width to 45 characters and add a style
-attribute that should try to set the width of the input box to the
-available width.
+In this case we force the system to use the ``TextWidget`` for the name, set
+the display width to 45 characters and add a style attribute that should try
+to set the width of the input box to the available width.
-The second possibility to change the widget of a field is to write a
-custom view class. In there, custom widgets are easily realized
-using the CustomWidget wrapper class. Here is a brief example::
+The second possibility to change the widget of a field is to write a custom
+view class. In there, custom widgets are easily realized using the
+CustomWidget wrapper class. Here is a brief example::
from zope.formlib.widget import CustomWidget
from zope.formlib.widget import TextWidget
@@ -558,23 +781,23 @@
class SomeView:
name_widget = CustomWidget(CustomTextWidget)
-- Line 1: Since ``CustomWidget`` is presentation type independent, it
- is defined in ``zope.app.form.widget``.
+- Line 1: Since ``CustomWidget`` is presentation type independent, it is
+ defined in ``zope.app.form.widget``.
-- Line 4-5: You simply extend an existing widget. Here you can
- overwrite everything, including the ``_validate()`` method.
+- Line 4-5: You simply extend an existing widget. Here you can overwrite
+ everything, including the ``_validate()`` method.
-- Line 7-8: You can hook in the custom widget by adding an attribute
- called name_widget, where name is the name of the field. The value
- of the attribute is a ``CustomWidget`` instance. ``CustomWidget``
- has only one required constructor argument, which is the custom
- widget for the field. Other keyword arguments can be specified as
- well, which will be set as attributes on the widget.
+- Line 7-8: You can hook in the custom widget by adding an attribute called
+ name_widget, where name is the name of the field. The value of the
+ attribute is a ``CustomWidget`` instance. ``CustomWidget`` has only one
+ required constructor argument, which is the custom widget for the field.
+ Other keyword arguments can be specified as well, which will be set as
+ attributes on the widget.
-More information about schemas can be found in the README.txt file of
-the ``zope.schema`` package.
+More information about schemas can be found in the README.txt file of the
+``zope.schema`` package.
-This concludes our introduction to schemas and forms. For examples
-of schemas and forms in practice, see the tutorial.
+This concludes our introduction to schemas and forms. For examples of
+schemas and forms in practice, see the tutorial.
.. _http://localhost:8080/++apidoc++: http://localhost:8080/++apidoc++
Modified: bluebream/website/docs/v1.0/new/index.rst
===================================================================
--- bluebream/website/docs/v1.0/new/index.rst 2010-08-11 18:37:22 UTC (rev 115639)
+++ bluebream/website/docs/v1.0/new/index.rst 2010-08-12 02:32:34 UTC (rev 115640)
@@ -2,7 +2,6 @@
============
.. toctree::
- :numbered:
:maxdepth: 2
whatsnew-1.0
Modified: bluebream/website/docs/v1.0/reference/index.rst
===================================================================
--- bluebream/website/docs/v1.0/reference/index.rst 2010-08-11 18:37:22 UTC (rev 115639)
+++ bluebream/website/docs/v1.0/reference/index.rst 2010-08-12 02:32:34 UTC (rev 115640)
@@ -2,7 +2,6 @@
=========
.. toctree::
- :numbered:
:maxdepth: 2
appwsgi
More information about the checkins
mailing list