How Formulator Eats Its Own Dogfood

  **NOTE**: You do not have to read this or understand this in order to
  use or even extend Formulator. Your brain may explode. Have fun.

  Formulator eats its own dogfood; fields have editable properties
  also represented by fields. A field class may contain an instance of
  itself in the end! This is accomplished by some hard to comprehend
  code, which I've still tried to write down as clearly as
  possible. Since at times I still can't figure it out myself, I've
  included this textual description.

The following files are in play (in 'Products/Formulator'):

  'FieldRegistry.py'

    All field classes are registered here (instead of with the
    standard Zope addable product registry).

  'Field.py'

    The main Field classes.

  'Form.py'

    The main Form classes. BasicForm is used internally for Forms
    without any web management UI. PythonForm is a form with a web UI
    (derived from ObjectManager).

  'StandardFields.py'
 
    Contains a bunch of standard fields that can be used by Formulator,
    such as StringField, IntegerField and TextArea field.

  'DummyField.py'

    Contains a dummy implementation of a field that can be used by
    fields before the field classes have been fully defined.

  'Widget.py'

    Contains the code for displaying a field as HTML. A widget has a
    'property_names' list associated with it, as well a number of
    class attributes for the fields that help define the parameters of
    the widget (dimensions, default value, etc). These are in fact not
    real fields at widget creation time, but DummyField instances.

  'Validator.py'

    Contains the code for validating field input. Like a widget, it
    contains a 'property_names' list and a number of
    field-but-not-really (DummyField) class attributes.

  '__init__.py'

    Sets up the fields first, and then registers the Formulator
    product (Formulator Form addable) with Zope itself. Somewhat more
    complicated than the average Product __init__.py.

  'FieldHelpTopic.py'
 
    Used to make the Zope help system automatically generate help for
    each field class.

  'HelperFields.py'

    Collects helper (internal) fields together for easy importing.

  'MethodField.py'

    Experimental MethodField. Right now only used internally by
    ListFields.

  'ListTextAreaField.py'

    Used internally by ListFields.

  'www' 
 
    This directory contains dtml files and icons used in the
    management screens of Formulator.

  'help'

    Help files.

Startup Sequence

  Before 'initialize()' in '__init__.py' is called:

    * the widget and validator classes is initialized, using the
      dummy FieldProperty objects as if they are fields as class
      attributes.
 
    * Singleton widget instance and validator instance objects are
      created.

    * The field classes is initialized, with widget and validator
      class attributes.

    * A singleton FieldRegistry object is created.

  'initialize()' - fields are registered with FieldRegistry:
 
    * A reference to the field class is stored in the FieldRegistry.

    * A BasicForm instance is created for each field class. Then the
      DummyFields associated with the field class' widget and validator
      objects are added to the BasicForm (to the Widget and the Validator
      groups).

    * Each field class now has a BasicForm containing the (dummy) fields
      that define its look and feel and behavior.
     
    * The appropriate field icons are also added to field classes. 

    * the Form is registered with Zope

    * finally, initializeFormulator in Form.py is called.

  'initialize()' - help is registered:

    * the .txt files in the help directory are registered with Zope.

    * A special FieldHelpTopic is created for each registered field.
 
  'initialize()' - final touches:

    * initializeForm in Form.py registers each (non-internal) field in
      the registry with Python Form, so that users can add the fields
      to the form.

    * initializeFields in the FieldRegistry makes the DummyFields that
      stood in for Field properties into real fields, now that
      everything else has been registered and set up.

Default properties

  It is (for me) hard to understand where default properties are
  coming from and should come from. Therefore I've created this
  description.

  A field has a 'default' property field. This is defined in the field
  *class* 'form' class attribute.

  A field has a 'default' property value. This is defined on the field
  *instance*, in the 'values' dictionary.

  Field properties have a 'default' field property and value of their
  own, as they are fields! Infinite regress? The *form* is shared by
  all fields of the same type, as it's a class attribute. So while
  there is infinite regress there, it does not cost infinite amounts
  of memory.

  A StringField has a 'default' property field that is itself a
  StringField. It also has a 'default' property value that is the
  empty string. On instantiation of a StringField, the 'default'
  property value is either taken from a keyword argument 'default'
  given to the __init__ function or, if none is present, from the
  default value of the 'default' property field.

  When a field is constructed using the Zope management interface this
  will use the manage_addField() method, defined on the form.
  manage_addField will create a field without any property values, so
  the constructor of the field will use the defaults, which it will
  take from the defaults of the property_fields.

  The propery_fields *have* (indirectly through FieldDummy instances)
  been constructed with default values given as keyword arguments.
 
  So this is how it all works out in the end. I hope. My brain just
  exploded; how's yours?

  Practical advice; don't think too hard about it. If you want
  particular property field defaults, pass them as keyword arguments
  when you construct a DummyField for use in a Widget or Validator;
  if instead you're fine with whatever default the field will come
  up with, don't pass a keyword argument.
   
  Creating new types of fields is actually quite easy; trust me.