dogfood.txt 6.05 KB
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181
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.