Fields 
========

**The standard schema fields**

The following tables shows the most common field types for use in
Dexterity schemata.
See the documentation on `creating schemata`_ for information about how to
use these.

Field properties
----------------

Fields are initialised with properties passed in their constructors.
To avoid having to repeat the available properties for each field, we’ll
list them once here, grouped into the interfaces that describe them.
You’ll see those interfaces again in the tables below that describe the
various field types.
Refer to the table below to see what properties a particular interface
implies.

=========== =================== ========== =================================================== 
Interface   Property            Type       Description                                         
=========== =================== ========== =================================================== 
IField      title               unicode    The title of the field. Used in the widget.         
\           description         unicode    A description for the field. Used in the widget.    
\           required            bool       Whether or not the field is required. Used for      
                                           form validation. The default is ``True``.           
\           readonly            bool       Whether or not the field is read-only. Default      
                                           is ``False``.                                       
\           default                        The default value for the field. Used in forms      
                                           and sometimes as a fallback value. Must be a        
                                           valid value for the field if set. The default       
                                           is ``None``.                                        
\           missing_value                  A value that represents "this field is not set".    
                                           Used by form validation. Defaults to ``None``. For  
                                           lists and tuples, it is sometimes useful to set     
                                           this to an empty list/tuple.                        
IMinMaxLen  min_length          int        The minimum required length. Used for string        
                                           fields. Default is ``0``.                           
\           max_length          int        The maximum allowed length. Used for string         
                                           fields. Default is ``None`` (no check).             
IMinMax     min                            The minimum allowed value. Must be a valid value    
                                           for the field, e.g. for an ``Int`` field this       
                                           should be an integer. Default is ``None`` (no       
                                           check).                                             
\           max                            The maximum allowed value. Must be a valid value    
                                           for the field, e.g. for an Int field this should    
                                           be an integer. Default is ``None`` (no check).      
ICollection value_type                     Another ``Field`` instance that describes the             
                                           allowable values in a list, tuple or other          
                                           collection. Must be set for any collection field.   
                                           One common usage is to set this to a ``Choice``,    
                                           to model a multi-selection field with a vocabulary. 
\           unique              bool       Whether or not values in the collection must be     
                                           unique. Usually not set directly – use a ``Set``    
                                           or ``Frozenset`` to guarantee uniqueness in an      
                                           efficient way.                                      
IDict       key_type                       Another ``Field`` instance that describes the       
                                           allowable keys in a dictionary. Similar to the      
                                           ``value_type`` of a collection. Must be set.        
\           value_type                     Another ``Field`` instance that describes the       
                                           allowable values in a dictionary. Similar to the    
                                           ``value_type`` of a collection. Must be set.        
IObject     schema              Interface  An interface that must be provided by any object    
                                           stored in this field.                               
IRichText   default_mime_type   str        Default MIME type for the input text of a rich      
                                           text field. Defaults to ``text/html``.              
\           output_mime_type    str        Default output MIME type for the transformed        
                                           value of a rich text field. Defaults to             
                                           ``text/x-html-safe``. There must be a               
                                           transformation chain in the ``portal_transforms``   
                                           tool that can transform from the input value to     
                                           the ``output`` value for the output property of     
                                           the ``RichValue`` object to contain a value.        
\           allowed_mime_types  tuple      A list of allowed input MIME types. The default     
                                           is ``None``, in which case the site-wide settings   
                                           (from the ``Markup`` control panel) will be used.   
=========== =================== ========== =================================================== 

Field types
-----------

The following tables describe the most commonly used field types,
grouped by the module from which they can be imported.

Fields in zope.schema
~~~~~~~~~~~~~~~~~~~~~

================= ============ ================================================================================= ================================
Name              Type         Description                                                                       Properties                      
================= ============ ================================================================================= ================================
Choice            N/A          Used to model selection from a vocabulary, which must be supplied.                See `vocabularies`_.            
                               Often used as the ``value_type`` of a selection field. The value                                                  
                               type is the value of the terms in the vocabulary.                                                                 
Bytes             str          Used for binary data.                                                             IField, IMinMaxLen              
ASCII             str          ASCII text (multi-line).                                                          IField, IMinMaxLen              
BytesLine         str          A single line of binary data, i.e. a ``Bytes`` with newlines                      IField, IMinMaxLen              
                               disallowed.                                                                                                       
ASCIILine         str          A single line of ASCII text.                                                      IField, IMinMaxLen              
Text              unicode      Unicode text (multi-line). Often used with a WYSIWYG widget,                      IField, IMinMaxLen              
                               although the default is a text area.                                                                              
TextLine          unicode      A single line of Unicode text.                                                    IField, IMinMaxLen              
Bool              bool         ``True`` or ``False``.                                                            IField                          
Int               int, long    An integer number. Both ints and longs are allowed.                               IField, IMinMax                 
Float             float        A floating point number.                                                          IField, IMinMax                 
Tuple             tuple        A tuple (non-mutable).                                                            IField, ICollection, IMinMaxLen 
List              list         A list.                                                                           IField, ICollection, IMinMaxLen 
Set               set          A set.                                                                            IField, ICollection, IMinMaxLen 
Frozenset         frozenset    A frozenset (non-mutable).                                                        IField, ICollection, IMinMaxLen 
Password          unicode      Stores a simple string, but implies a password widget.                            IField, IMinMaxLen              
Dict              dict         Stores a dictionary. Both ``key_type`` and ``value_type`` must be set to fields.  IField, IMinMaxLen, IDict       
Datetime          datetime     Stores a Python ``datetime`` (not a Zope 2 ``DateTime``).                         IField, IMinMax                 
Date              date         Stores a python ``date``.                                                         IField, IMinMax                 
Timedelta         timedelta    Stores a python ``timedelta``.                                                    IField, IMinMax                 
SourceText        unicode      A textfield intended to store source text (e.g. HTML or Python code).             IField, IMinMaxLen              
Object            N/A          Stores a Python object that conforms to the interface given as the                IField, IObject                 
                               ``schema``. There is no standard widget for this.                                                                 
URI               str          A URI (URL) string.                                                               IField, MinMaxLen               
Id                str          A unique identifier – either a URI or a dotted name.                              IField, IMinMaxLen              
DottedName        str          A dotted name string.                                                             IField, IMinMaxLen              
InterfaceField    Interface    A Zope interface.                                                                 IField                          
Decimal           Decimal      Stores a Python ``Decimal``. Requires version 3.4 or later of                     IField, IMinMax                 
                               `zope.schema`_. Not available by default in Zope 2.10.                                                            
================= ============ ================================================================================= ================================

Fields in ``plone.namedfile.field``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

See `plone.namedfile`_ and `plone.formwidget.namedfile`_ for more
details.

=============== =============== ================================================================================= ==========
Name            Type            Description                                                                       Properties
=============== =============== ================================================================================= ==========
NamedFile       NamedFile       A binary uploaded file. Normally used with the widget from                        IField    
                                `plone.formwidget.namedfile`_.                                                              
NamedImage      NamedImage      A binary uploaded image. Normally used with the widget from                       IField    
                                `plone.formwidget.namedfile`_.                                                              
NamedBlobFile   NamedBlobFile   A binary uploaded file stored as a ZODB BLOB. Requires the ``[blobs]`` extra to   IField    
                                `plone.namedfile`_. Otherwise identical to ``NamedFile``.                                   
NamedBlobImage  NamedBlobImage  A binary uploaded image stored as a ZODB BLOB. Requires the ``[blobs]`` extra to  IField    
                                `plone.namedfile`_. Otherwise identical to ``NamedImage``.                                  
=============== =============== ================================================================================= ==========

Fields in ``z3c.relationfield.schema``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

See `z3c.relationfield`_ for more details.

================= ================ ================================================================ ===============
Name              Type             Description                                                      Properties     
================= ================ ================================================================ ===============
Relation          RelationValue    Stores a single ``RelationValue``.                               IField      
RelationList      list             A ``List`` field that defaults to ``Relation`` as the value type See ``List`` 
RelationChoice    RelationValue    A ``Choice`` field intended to store ``RelationValue``’s         See ``Choice``
================= ================ ================================================================ ===============

Fields in `plone.app.textfield`_
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

See `plone.app.textfield`_  for more details.

========= ============== ====================================================================================== ==================
Name      Type           Description                                                                            Properties        
========= ============== ====================================================================================== ==================
RichText  RichTextValue  Stores a ``RichTextValue``, which encapsulates a raw text value, the source MIME type, IField, IRichText 
                         and a cached copy of the raw text transformed to the default output MIME type.                           
========= ============== ====================================================================================== ==================

.. _creating schemata: ../schema-driven-types.html#the-schema
.. _plone.app.textfield: http://pypi.python.org/pypi/plone.app.textfield
.. _plone.formwidget.namedfile: http://pypi.python.org/pypi/plone.formwidget.namedfile
.. _plone.namedfile: http://pypi.python.org/pypi/plone.namedfile
.. _vocabularies: ../advanced/vocabularies.html
.. _z3c.relationfield: http://pypi.python.org/pypi/z3c.relationfield
.. _zope.schema: http://pypi.python.org/pypi/zope.schema
