pax_global_header 0000666 0000000 0000000 00000000064 12015425344 0014512 g ustar 00root root 0000000 0000000 52 comment=a7cbd68f484589542f8769f62bbb414d55ab8dee erp5-a7cbd68f484589542f8769f62bbb414d55ab8dee-product-Formulator-help/ 0000775 0000000 0000000 00000000000 12015425344 0024240 5 ustar 00root root 0000000 0000000 erp5-a7cbd68f484589542f8769f62bbb414d55ab8dee-product-Formulator-help/product/ 0000775 0000000 0000000 00000000000 12015425344 0025720 5 ustar 00root root 0000000 0000000 erp5-a7cbd68f484589542f8769f62bbb414d55ab8dee-product-Formulator-help/product/Formulator/ 0000775 0000000 0000000 00000000000 12015425344 0030052 5 ustar 00root root 0000000 0000000 erp5-a7cbd68f484589542f8769f62bbb414d55ab8dee-product-Formulator-help/product/Formulator/help/ 0000775 0000000 0000000 00000000000 12015425344 0031002 5 ustar 00root root 0000000 0000000 BasicForm.py 0000664 0000000 0000000 00000001746 12015425344 0033152 0 ustar 00root root 0000000 0000000 erp5-a7cbd68f484589542f8769f62bbb414d55ab8dee-product-Formulator-help/product/Formulator/help class BasicForm: """ Use BasicForm to construct and use Formulator forms from Python code. """ __extends__ = ('Formulator.Form.Form',) def add_field(field, group=None): """ Add a field to a group on the form. The 'group' argument is optional, and if no group is given the field is added to the first group. The field is always added to the bottom of the group. Permission -- 'Change Formulator Forms' """ def add_fields(fields, group=None): """ Add a list of fields to a on the form. The 'group' argument is optional; if no group is given the fields are added to the first group. Fields are added in the order given to the bottom of the group. Permission -- 'Change Formulator Forms' """ def remove_field(field): """ Remove a particular field from the form. Permission -- 'Change Formulator Forms' """ Field.py 0000664 0000000 0000000 00000012152 12015425344 0032321 0 ustar 00root root 0000000 0000000 erp5-a7cbd68f484589542f8769f62bbb414d55ab8dee-product-Formulator-help/product/Formulator/help class Field: """Formulator field base class; shared functionality of all fields. """ def initialize_values(dict): """ Initialize the values of field properties. 'dict' is a dictionary. A dictionary entry has as key the property id, and as value the value the property should take initially. If there is no entry in the dictionary for a particular property, the default value for that property will be used. All old property values will be cleared. Permission -- 'Change Formulator Fields' """ def initialize_overrides(): """ Clear (initialize to nothing) overrides for all properties. Permission -- 'Change Formulator Fields' """ def has_value(id): """ Returns true if a property with name 'id' exists. Permission -- 'Access contents information' """ def get_orig_value(id): """ Get value of property without looking at possible overrides. Permission -- 'Access contents information' """ def get_value(id, **kw): """ Get property value for an id. Call override if override is defined, otherwise use property value. Alternatively the dictionary interface can also be used ('__getitem__()'). Keywords arguments can optionally be passed, which will end up in the namespace of any TALES expression that gets called. Permission -- 'Access contents information' """ def __getitem__(self, key): """ Get property value for an id. Call override if override is defined, otherwise use property value. Alternatively 'get_value()' can be used to do this explicitly. In Python, you can access property values using:: form.field['key'] and in Zope Page Templates you can use the following path notation:: form/field/key Permission -- 'Access contents information' """ def get_override(id): """ Get the override method for an id, or empty string if no such override method exists. Permission -- 'Access contents information' """ def is_required(): """ A utility method that returns true if this field is required. (checks for 'required' property). Permission -- 'Access contents information' """ def get_error_names(): """ Get all keys of error messages that the validator of this field provides. Permission -- 'View management screens' """ def get_error_message(name): """ Get the contents of a particular error message with key 'name'. Permission -- 'View management screens' """ def render(value=None, REQUEST=None): """ Get the rendered HTML for the widget of this field, to display the fields on a form. 'value' -- If the 'value' parameter is not None, this will be the pre-filled value of the field on the form. 'REQUEST' -- If the 'value' parameter is 'None' and 'REQUEST' is supplied, raw (unvalidated) values will be looked up in 'REQUEST' to display in the field. If neither 'value' or 'REQUEST' are supplied, the field's default value will be used instead. Permission -- 'View' """ def render_from_request(REQUEST): """ A convenience method to render the field widget using the raw data from 'REQUEST' if any is available. The field's default value will be used if no raw data can be found. Pemrissions -- 'View' """ def render_sub_field(id, value=None, REQUEST=None): """ Render a sub field of this field. This is used by composite fields that are composed of multiple sub fields such as 'DateTimeField'. 'id' is the id of the sub field. 'value' and 'REQUEST' work like in 'render()', but for the sub field. Permission -- 'View' """ def render_sub_field_from_request(id, REQUEST): """ A convenience method to render a sub field widget from 'REQUEST' (unvalidated data). Permission -- 'View' """ def validate(REQUEST): """ Validate this field using the raw unvalidated data found in 'REQUEST'. Returns the validated and processed value, or raises a ValidationError. Permission -- 'View' """ def validate_sub_field(id, REQUEST): """ Validate a sub field of this field using the raw unvalidated data found in 'REQUEST'. This is used by composite fields composed of multiple sub fields such as 'DateTimeField'. Returns the validated and processed value, or raises a ValidationError. Permission -- 'View' """ def render_view(value): """ Render supplied value for viewing, not editing. This can be used to show form results, for instance. Permission -- 'View' """ Form.py 0000664 0000000 0000000 00000020462 12015425344 0032204 0 ustar 00root root 0000000 0000000 erp5-a7cbd68f484589542f8769f62bbb414d55ab8dee-product-Formulator-help/product/Formulator/help class Form: """A Formulator Form; this is the base class of all forms. """ def move_field_up(field_id, group): """ Move the field with 'field_id' up in the group with name 'group'. Returns 1 if move succeeded, 0 if it failed. Permission -- 'Change Formulator Forms' """ def move_field_down(field_id, group): """ Move the field with 'field_id' down in the group with name 'group'. Returns 1 if move succeeded, 0 if it failed. Permission -- 'Change Formulator Forms' """ def move_field_group(field_ids, from_group, to_group): """ Move a number of field ids in the list 'field_ids' from 'from_group' to 'to_group'. Returns 1 if move succeeded, 0 if it failed. Permission -- 'Change Formulator Forms' """ def add_group(group): """ Add a new group with the name 'group'. The new group must have a unique name in this form and will be added to the bottom of the list of groups. Returns 1 if the new group could be added, 0 if it failed. Permission -- 'Change Formulator Forms' """ def remove_group(group): """ Remove an existing group with the name 'group'. All fields that may have been in the group will be moved to the end of the first group. The first group can never be removed. Returns 1 if the group could be removed, 0 if it failed. Permission -- 'Change Formulator Forms' """ def rename_group(group, name): """ Give an existing group with the name 'group' a new name. The new name must be unique. Returns 1 if the rename succeeded, 0 if it failed. Permission -- 'Change Formulator Forms' """ def move_group_up(group): """ Move the group with name 'group' up in the list of groups. Returns 1 if the move succeeded, 0 if it failed Permission -- 'Change Formulator Forms' """ def move_group_down(group): """ Move the group with name 'group' down in the list of groups. Returns 1 if the move succeeded, 0 if it failed. Permission -- 'Change Formulator Forms' """ def get_fields(): """ Returns a list of all fields in the form (in all groups). The order of the fields will be field order in the groups, and the groups will be in the group order. Permission -- 'View' """ def get_field_ids(): """ As 'get_fields()', but instead returns a list of ids of all the fields. Permission -- 'View' """ def get_fields_in_group(group): """ Get a list in field order in a particular group. Permission -- 'View' """ def has_field(id): """ Check whether the form has a field of a certain id. Returns true if the field exists. Permission -- 'View' """ def get_field(id): """ Get a field with a certain id. Permission -- 'View' """ def get_groups(): """ Get a list of all groups in the form, in group order. Permission -- 'View' """ def render(self, dict=None, REQUEST=None): """ Returns a basic HTML rendering (in a table) of this form. For more sophisticated renderings you'll have to write DTML or ZPT code yourself. You can supply an optional 'dict' argument; this should be a dictionary ('_', the namespace stack, is legal). The dictionary can contain data that should be pre-filled in the form (indexed by field id). The optional 'REQUEST' argument can contain raw form data, which will be used in case nothing can be found in the dictionary (or if the dictionary does not exist). Permission -- 'View' """ def validate(REQUEST): """ Validate all the fields in this form, looking in REQUEST for the raw field values. If any validation error occurs, ValidationError is raised and validation is stopped. Returns a dictionary with as keys the field ids and as values the validated and processed field values. Exceptions that are raised can be caught in the following way (also in through the web Python scripts):: from Products.Formulator.Errors import ValidationError try: myform.validate(REQUEST) except ValidationError, e: print 'error' # handle error 'e' Permission -- 'View' """ def validate_to_request(REQUEST): """ Validate all the fields in this form, looking in REQUEST for the raw field values. If any validation error occurs, ValidationError is raised and validation is stopped. Returns a dictionary with as keys the field ids and as values the validated and processed field values. In addition, this result will also be added to REQUEST (also with the field ids as keys). Exceptions that are raised can be caught in the following way (also in through the web Python scripts):: from Products.Formulator.Errors import ValidationError try: myform.validate_to_request(REQUEST) except ValidationError, e: print 'error' # handle error 'e' Permission -- 'View' """ def validate_all(REQUEST): """ Validate all the fields in this form, looking in REQUEST for the raw field values. If any ValidationError occurs, they are caught and added to a list of errors; after all validations a FormValidationError is then raised with this list of ValidationErrors as the 'errors' attribute. Returns a dictionary with as keys the field ids and as values the validated and processed field values. Exceptions that are raised can be caught in the following way (also in through the web Python scripts):: from Products.Formulator.Errors import ValidationError, FormValidationError try: myform.validate_all(REQUEST) except FormValidationError, e: print 'error' # handle error 'e', which contains 'errors' Permission -- 'View' """ def validate_all_to_request(REQUEST): """ Validate all the fields in this form, looking in REQUEST for the raw field values. If any ValidationError occurs, they are caught and added to a list of errors; after all validations a FormValidationError is then raised with this list of ValidationErrors as the 'errors' attribute. Returns a dictionary with as keys the field ids and as values the validated and processed field values. In addition, the validated fields will be added to REQUEST, as in 'validate_to_request()'. This will always be done for all fields that validated successfully, even if the validation of other fields failed and a FormValidationError is raised. Exceptions that are raised can be caught in the following way (also in through the web Python scripts):: from Products.Formulator.Errors import ValidationError, FormValidationError try: myform.validate_all_to_request(REQUEST) except FormValidationError, e: print 'error' # handle error 'e', which contains 'errors' Permission -- 'View' """ def session_store(session, REQUEST): """ Store any validated form data in REQUEST in a session object (Core Session Tracking). Permission -- 'View' """ def session_retrieve(session, REQUEST): """ Retrieve validated form data from session (Core Session Tracking) into REQUEST. Permission -- 'View' """ def header(): """ Get the HTML code for the start of a form. This produces a '
'). Permission -- 'View' """ ZMIForm.py 0000664 0000000 0000000 00000001331 12015425344 0032556 0 ustar 00root root 0000000 0000000 erp5-a7cbd68f484589542f8769f62bbb414d55ab8dee-product-Formulator-help/product/Formulator/help class ZMIForm: """Form used from Zope Management Interface. Inherits from ObjectManager to present folderish view. """ __extends__ = ('Formulator.Form.Form', 'OFSP.ObjectManager.ObjectManager', 'OFSP.ObjectManagerItem.ObjectManagerItem') def manage_addField(id, title, fieldname, REQUEST=None): """ Add a new field with 'id' and 'title' of field type 'fieldname' to this ZMIForm. 'REQUEST' is optional. Note that it's better to use BasicForm and 'add_field' if you want to use Formulator Forms outside the Zope Management Interface. Permission -- 'Change Formulator Forms' """ dogfood.txt 0000664 0000000 0000000 00000014067 12015425344 0033115 0 ustar 00root root 0000000 0000000 erp5-a7cbd68f484589542f8769f62bbb414d55ab8dee-product-Formulator-help/product/Formulator/help 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. fieldEdit.txt 0000664 0000000 0000000 00000004725 12015425344 0033365 0 ustar 00root root 0000000 0000000 erp5-a7cbd68f484589542f8769f62bbb414d55ab8dee-product-Formulator-help/product/Formulator/help Formulator Field - Edit Description A field has a number of properties that determine its look and feel as well as its behavior. You can configure these properties in this tab. You can also use the TALES tab and the Override tab to associate dynamic behavior with field properties, though the Override tab is eventually to be phased out in favor of the TALES tab. Overridden fields will have their names be shown in square brackets. Which properties appear in this view depends on what kind of field you are editing. Each field has two sets of properties; widget properties and validator properties. Widget properties The widget properties determine the look and feel of the field that you see on the web page (which HTML code is generated for the field); i.e. what GUI *widget* you see. A very common widget property shared by all fields is called 'Title'; all fields have titles -- the name you will see when the field is displayed on the screen. Another very common widget property is the 'Default' value of the widget. This is what will be filled in before the user changes anything to the form, unless you pass a value to the 'render' function; see the API reference for more information. Many widgets also have size information; the StringField for instance has a 'Display width' property which determines how large the field should appear on the screen, as well as a 'Maximum input' property that determines how much the user can enter (though this is independent from actual server-side validation). For some widget properties such as 'Maximum input' in StringField you can set the value to '0'; in that the HTML widget won't care how much the user inputs. Validator properties This set of properties determines how the field validates the information that is submitted for this field. A very common validator property is the 'required' property. If a field is required, the field cannot be left empty by the user when submitting a web page. Validation in that case will result in failure. In case of the 'StringField', one validation property is called 'Maximum length'; the field cannot contain more characters than that. For some validator properties such as 'Maximum length' in StringField, you can set the value to '0'. The validator will then not care how much the user entered -- there won't be any maximum. fieldMessages.txt 0000664 0000000 0000000 00000000514 12015425344 0034237 0 ustar 00root root 0000000 0000000 erp5-a7cbd68f484589542f8769f62bbb414d55ab8dee-product-Formulator-help/product/Formulator/help Formulator Field - Messages Description Each field has a set of messages that can be displayed in case validation fails. Standard messages are provided, but you can change these messages for the particular field in this view. The message text is the 'error_text' that will show up in case validation fails. fieldOverride.txt 0000664 0000000 0000000 00000004023 12015425344 0034246 0 ustar 00root root 0000000 0000000 erp5-a7cbd68f484589542f8769f62bbb414d55ab8dee-product-Formulator-help/product/Formulator/help Formulator Field - Override Description Note: the Override tab is being phased out in favor of the TALES tab. Sometimes you'd like a field property to be dynamic instead of just a value filled in in the 'Edit' tab of the field. If you fill in the name of an 'override' method for a property in the Override tab, that method will be called whenever you (or the code) asks for the value of that property using get_value(). Properties which are overridden are shown between square brackets ([ and ]) in the main Edit tab, and the value of the property in the edit tab will be ignored. To stop using an override for a particular property, remove the method name in the override tab. An override method should return an object of the same type as the property field would return after validation. For instance, an override method for a StringField would return a simple string, for an IntegerField it would return an integer, and for a CheckBoxField it would return true or false (or something that can be interpreted that way). Example A good example of the use of the override tab is the 'items' property of a ListField; frequently you may want to get these items from elsewhere, for instance from a database. In this case you would fill in the name of the override method for 'items' that retrieves the right data. The 'right data' in this case is that which validation of the builtin field ListTextArea would return. This is a list of tuples, one tuple for each element. Each tuple consists of two strings; the name that should be displayed to the user for that item, and the actual value that will be submitted. This for instance is a Python script 'random_numbers' that will return ten random numbers as the elements:: # random_numbers import random result = [] for i in range(10): number = random.randint(0, 100) tuple = str(number), str(number) result.append(tuple) return result fieldTales.txt 0000664 0000000 0000000 00000007352 12015425344 0033547 0 ustar 00root root 0000000 0000000 erp5-a7cbd68f484589542f8769f62bbb414d55ab8dee-product-Formulator-help/product/Formulator/help Formulator Field - TALES Description Sometimes you'd like a field property to be dynamic instead of just a value filled in in the 'Edit' tab of the field. To make your fields more dynamic, you can enter TALES expressions in the TALES tab. Whenever you (or some code) asks for the value of that field property next with 'get_value()', the TALES expression will be evaluated and the result will be the value of that property. Properties which are overridden with a TALES expression are shown between square brackets ([ and ]) in the main Edit tab, and the value of the property in the edit tab will be ignored. To stop using a TALES expression for a particular property, remove the expression in the TALES tab. A TALES expression should return an object of the same type as the property field would return after validation. For instance, a TALES expression for a StringField would return a simple string, for an IntegerField it would return an integer, and for a CheckBoxField it would return true or false (or something that Python accepts as such). More information about TALES The specification: http://dev.zope.org/Wikis/DevSite/Projects/ZPT/TALES%20Specification%201.3 Predefined variables Two predefined variables are in the expression namespace, 'form', and 'field'. You can use them to call their methods (though one should be careful with some, to avoid infinite recursion), and also methods and scripts that are the form's (or field's) acquisition context. You can also pass them to the methods you call. Relation to the Override tab The TALES tab is meant to eventually obsolute the Override tab; the use of the Override tab can therefore be considered deprecated. Once Zope Page Templates (and thus TALES) become part of the Zope core distribution, I plan to phase out the Override tab altogether. If an override tab says this: foo where foo is a Python Script that is acquired by the form, for instance, you can now do: python:form.foo() This is longer, but the advantage is that you can now pass parameters, for instance: python:form.bar(1, 'hey') Example A good example of the use of the TALES tab is the 'items' property of a ListField; frequently you may want to get these items from elsewhere, for instance from a database. In this case you would fill in the name of the override method for 'items' that retrieves the right data. The 'right data' in this case is that which validation of the builtin field ListTextArea would return. This is a list of tuples, one tuple for each element. Each tuple consists of two strings; the name that should be displayed to the user for that item, and the actual value that will be submitted. This for instance is a Python script 'random_numbers' that will return 'n' random numbers as the elements, where 'n' is the (single) parameter to the Python script:: # random_numbers import random result = [] for i in range(n): number = random.randint(0, 100) tuple = str(number), str(number) result.append(tuple) return result You can call this script with the following expression for items, which will give 10 random numbers. python:form.random_numbers(10) Caveat: in the current Formulator implementation it is very hard to actually go through validation successfully, as exactly the same random numbers need to be generated twice; once for the display phase, and once during the validation phase. The implementation currently assumes the list won't change through multiple calls to calculate the 'items' property. fieldTest.txt 0000664 0000000 0000000 00000001611 12015425344 0033406 0 ustar 00root root 0000000 0000000 erp5-a7cbd68f484589542f8769f62bbb414d55ab8dee-product-Formulator-help/product/Formulator/help Formulator Field - Test Description With the 'test' view, you can test the look and feel and validation behavior of the field. Fill in the field and press the 'Test' button to test it. You will now see the test form again. If your input was successfully validated by the field, you will see a message 'Test successful:' above the test form, followed by the result of the validation processing (this may be empty text in case you filled in nothing). If the field could not be validated, you will see the message 'There was a validation error:' instead, followed by a description of the error: * 'field_id' gives the field name. * 'error_key' is the name of the error message; you can find it in the 'messages' tab. * 'error_text' is the actual text associated with the 'error_key'; you can modify it in the 'messages' tab. formContents.txt 0000664 0000000 0000000 00000001471 12015425344 0034150 0 ustar 00root root 0000000 0000000 erp5-a7cbd68f484589542f8769f62bbb414d55ab8dee-product-Formulator-help/product/Formulator/help Formulator Form - Contents Description The contents view of a Formulator Form behaves much like normal Zope Folder. The difference is that the only objects listed are Formulator Fields, and if you look at the 'Add' list you can see you can only add different types of fields on this screen. Similarly, you can't copy and paste objects into the form that are not fields, and it is not allowed to copy fields to normal folders either. If you click on a field, you will enter the field edit screen, where you can modify field properties. Other Help The other tabs of the Formulator Form contain their own help text; fields also provide help. For more information on how to use the contents view of Formulator Form, look at the online help for Folders. formOrder.txt 0000664 0000000 0000000 00000006547 12015425344 0033437 0 ustar 00root root 0000000 0000000 erp5-a7cbd68f484589542f8769f62bbb414d55ab8dee-product-Formulator-help/product/Formulator/help Formulator Form - Order Description The 'order' view allows you to change the order in which fields should be displayed in the form. You can also group fields together; this may be helpful when you create a complicated form. Any field that gets added to the form ends up in the first group. This group always exists and cannot be removed. You can click on the field id to go directly to the field management screen. Note that you *cannot* add or remove any fields in this form; you have to use the main 'contents' view of the form for that. How this information is used The order and grouping information is used internally by the 'test' tab of the form, and you can also use it in your own code. See the Formulator API Reference (to be written; for now read the source!) for more information on how to do that. Reordering fields inside a group You can reorder fields in a group by moving them up and down in the group. Select the field you want to move using the checkbox in front of the field id. Then click on the 'Move Up' or 'Move Dn' button, to move the field up or down respectively. You will see a feedback message at the top of the screen. You can only move a single field at a time this way, you select only the field you want to move! Creating a new group The first group has a button called 'Create' at the bottom, with an input box above it. Fill in the name of the new group that you want to create there, and press the 'Create' button. The new group will be added (as the last group visible). How the groups are displayed In order to show more information on a single screen, the groups are ordered in columns from left to right, then in rows from top to bottom. The 'settings' view allows you to modify how many groups should appear in a single row (the default is 4 groups). Changing this has no impact on the functionality of the form itself. When you add a new group, it will be added to the right of the current last group, if this still fits in a row. Otherwise a new row will be created and the group will be displayed there. Moving fields to a different group When you create a new group, it remains empty. You can move several fields into a group by using the 'Transfer' button of a group. First select one ore more fields in an old group that you want to move away. Then, use the 'Move to:' dropdown list to select the group to which you want to move the selected fields. Then, press the 'Transfer' button. The fields should now disappear from the origin group and appear in the target group. Reordering groups You can change the order of the gropus by using the 'Move Up' and 'Move Dn' buttons in the 'Group' section of a group. This moves the entire group in the group order. You cannot move the first group (and it therefore has no group movement buttons). Renaming groups You can rename a group by filling in the new name in the input box above the 'Rename' button, and then pressing that button. Removing groups You can remove a group by pressing the 'Remove' button in the 'Group' section of the group. The entire group will disappear. Any fields that were in the group will move to the bottom of the first group; you cannot lose any fields this way. formSettings.txt 0000664 0000000 0000000 00000002766 12015425344 0034163 0 ustar 00root root 0000000 0000000 erp5-a7cbd68f484589542f8769f62bbb414d55ab8dee-product-Formulator-help/product/Formulator/help Formulator Form - Settings Description You can set some basic settings of the form. Number of groups in row (in order tab) Change the amount of groups that should appear in a single row in the 'order' view. The default is '4'. Form action The method the form should call when it is submitted. If you use the 'header()' method of Form, it will use this as the 'action' attribute of the HTML form. Form method The submit method of the form (not to be confused with a method in Python of Zope). 'POST' is generally used for forms that change underlying data, while 'GET' is generally used for forms that do a query. In case of 'GET' the fields in the form will be encoded in the URL (so you can for instance bookmark the URL). The 'header()' method of the Form will use this as the 'method' attribute of the HTML form. Form enctype The encoding type of the form. If no encoding type is selected, the default for HTML will be used, which is 'application/x-www-form-urlencoded'. No enctype is therefore usually just fine. For forms that allow the uploading of a file, use 'multipart/form-data'. The 'header()' method of the Form will use this as the 'enctype' attribute of the HTML form. Upgrade The 'Upgrade' button in this section is really not useful yet. It's used internally to upgrade unreleased development versions of Formulator to the current version. Perhaps this will become more useful in the future. formTest.txt 0000664 0000000 0000000 00000002011 12015425344 0033261 0 ustar 00root root 0000000 0000000 erp5-a7cbd68f484589542f8769f62bbb414d55ab8dee-product-Formulator-help/product/Formulator/help Formulator Form - Test Description In this view, you can test your form. The fields in your form will be rendered as a simple HTML form. The fields are grouped and come in a certain order; this can be defined with the form's 'order' tab. You can fill in some values and click on the 'Test' button to submit the form. You will now see the test form again. If all of your input was successfully validated by the fields in the form, you the message 'All fields were validated correctly' above your form. If some of the fields could not be validated, you will instead see the message 'Not all fields could be validated' appear, and a list with the validation errors: * 'field_id' indicates the field that gave this validation error. * 'error_key' is the name of the error message; you can find it on that field's 'messages' tab. * 'error_text' is the actual text associated with that 'error_key'; you can modify it on the field's messages tab. formXML.txt 0000664 0000000 0000000 00000001240 12015425344 0033005 0 ustar 00root root 0000000 0000000 erp5-a7cbd68f484589542f8769f62bbb414d55ab8dee-product-Formulator-help/product/Formulator/help Formulator Form - XML Description In this view, you can see an XML serialization of the form. If you are using FSForm along with FileSystemSite, you can use this XML by putting it on the filesystem as a .form file. FileSystemSite will then pick it up and reflect it into the ZODB. This way you can develop and maintain Formulator Forms on the filesystem. FileSystemSite can be found here: http://www.zope.org/Members/k_vertigo/Products/FileSystemSite To enable Formulator support for FileSystemSite, do a 'from Products.Formulator import FSForm' somewhere in your own code (for instance in your product's '__init__.py'). formulator_howto.txt 0000664 0000000 0000000 00000023527 12015425344 0035107 0 ustar 00root root 0000000 0000000 erp5-a7cbd68f484589542f8769f62bbb414d55ab8dee-product-Formulator-help/product/Formulator/help Formulator HOWTO Introduction This HOWTO is intended to give an introduction to the use of Formulator from the Zope Management Interface and from DTML, although much of this applies to use from ZPT or Python as well. Note that Formulator comes with online help for each tab as well as API help, so be sure to check that as well. This document will only give an overview of the possibilities and not all the details. Formulator Scope Formulator is a tool to create and validate web forms in Zope. Formulator takes care of the rendering of the fields in the form, as well as the validation and processing of the data that is submitted. Formulator's scope is limited to forms: "do web forms, web forms only, and web forms well." Formulator does currently not even take care of the precise layout of a form -- each form is layouted differently and thus layout is left to the developer. Formulator does allow for easy integration with external systems, however. Creating a Formulator Form and Fields It is easy to create a Formulator Form, just pick it from the add list and add it to a folder. I usually only have one form in a folder and call it 'form' to make automatic layout handling easier; I'll say more about the reason for this later. The default view of the form looks just like a folder, except that the only things that are addable are Formulator Fields. When you add a field to a form, it'll show up in the Form, just like an object shows up in a normal Zope Folder. Fields When you click on a field, you see a list of its properties in the field's 'Edit' screen. This is a good time to explain that Formulator has an extensive help system, and that if you click on 'help' in the 'Edit' screen you'll see a list with a short description of what each property does. If you click on the 'Test' tab in the Field, you will see the field displayed as it would appear in the form. If you fill in some value in the field and click on the 'Test' button, you can test its validation behavior. If everything could be validated and processed all right, you'll see the resulting value. If it could not be validated however, you see an error, showing the error_key and error_text. The best way to learn about what the different fields do and how their properties work is to try them out. Just change some properties and see what happens in the Test screen. And be sure to look at the help. Other Form tabs The form 'Test' tab is not difficult to explain; it shows all the fields you have added to the form. You can test the behavior of the entire form here. In the 'Order' part you can group fields and order them inside their groups. The order determines the order in which they appear on the 'Test' screen, and can also can be used in your own code. Initially there is only a single 'Default' group, but you can add new groups and change their names. In the 'Settings' tab you can determine the form properties. You can set the form submit action and method here, which you can later use with the 'header()' and 'footer()' methods of the form. Other Field tabs The field 'Override' screen allows you to make the field call an override method (most commonly a Python Script) for a property. Instead of using the property value in the 'Edit' screen, the method with the name listed in the override tab will be called to retrieve a value then. The returned value must be the same as the one that property's field generates; for an IntegerField this is an integer, for instance. The titles of overridden fields will be displayed between square brackets ('[ ]') in the 'Edit' screen. In the 'Messages' screen you can set the text of the error messages that field can generate upon validation errors. On the examples in this HOWTO All the examples in this HOWTO are contained in the file 'formulator_howto_examples.zexp', which you can download from the Formulator product page (http://www.zope.org/Members/faassen/formulator) and import into your Zope. In the examples, all the forms are called 'form'. Rendering a form manually with DTML ('manual' folder) First, I will show how to use DTML to manually layout a form. This takes the most work, but also allows the most flexibility. In all these examples I will assume the form is called 'form'. The form contains three fields; a StringField 'animal', a StringField 'color', and an IntegerField 'number'. 'index_html' is the DTML Method that does the manual layout::