Benefits Overview

Creating and editing a form

« Return to page index

This tutorial will show you how to create and maintain a plone formgen form.

Creating a form folder

    The form edit page has 6 Tabs at the top

    • Default
      1. Navigate to the folder you would like to contain your form.
      2. On the edit bar, usually green at the top of the page, click on the Add New drop down menu on the right.
      3. Select Form folder.
      4. Enter a title for your form.
      5. Enter a description for your form. This is usually a short summary of what the form is used for.
      6. If you want to change the text on the submit button, enter it in the Submit Button Label box.
      7. If you want a reset/clear button on your form, check the Show Reset Button box and enter a label.
      8. The Action adapters available for this form folder. Mailer is added to the form automatically. Below are descriptions of the available adapters.
        1. Mailer: Mailer is used to send the form contents to either the admin of the form or the person filling it out.
        2. Save Data: The save data adapter is used to save the data entered on the form temporarily in plone. The data in the save data adapter should be retrieved at least once a week to prevent loss. If the data is erased it will be lost.
        3. Custom Script Adapter: This will allow you to add a custom processing script to your form. It must be programmed in Python. Note: Do not use this unless you know what you are doing, it can cause problems with your form if it is not handled properly.
      9. The thanks page displays a page with a thank you message. The default page displays the information entered on the form.
      10. If your form will contain information you want encrypted check the Force SSL Connection box. This will force the browser to use the SSL protocol to communicate with the server.
      11. Form Prolog is a free form area for creating a header for your form. This can contain anything you want and be a long as you want.
      12. Form Epilogue is a free form area at the bottom or your form.
      13. The Local CSS fields allows you to change the look of your form folder with CSS.  This may be turned off by your site administrator.
      14. Block CSS Inheritance when checked, will remove any Local CSS entries from parent folders. This does not remove Theme CSS entries.
    • Categorization allows you to categorize your form for searches and collections.
    1. Tags Allow you to create organize your content on your site.  They can also be used to create Collections of items with the same tag.
    2. Location is the geographical location of for the content. This can also be used in collections.
    3. Language
  1. Dates allows you to publish and retract your form automatically
    1. Publishing Date is the date this form will be available for non logged in users to see. If left blank it will default to right now.
    2. Expiration Date is the date this form will become unavailable to non logged in users. If left blank the form will never expire.
  2. Ownership allows you to define who is responsible for the form and who owns it.
    1. Creators are the people who created the content for the form. Enter one name per line.
    2. Contributors are the people who contributed to the creation of the form.  Enter one name per line.
    3. Copyright is where you would enter any copyright information. Per University policy, the university generally claims copyright on all thing on it's systems.
  3. Settings
    1. Allow Comments allows the users of the page to leave comments at the bottom of the page.
    2. Exclude from navigation will leave the form off of the navigation bar.
    3. Enable next previous navigationadds a navigation link at the bottom of the page to go to the next page. (see the bottom of this page for an example.)

    Click the Save button

    After you fill out this information a basic form with 3 fields will be created.

        Adding fields to your form

        The default form folder starts out as a basic email form with email, subject, and comments fields. It alos has a mailer and a thanks page. To add fields to and remove fields from your form, do the following:

        1. Open the form folder.
        2. Click on the Quick Edit tab.
        3. Select the form field type from the toolbox on the right.
        4. Drag it to the form. An outline of the field will display on the form.
        5. Move it around until it is where you want it.
        6. Drop it.
        7. The default edit tab for the field will display in place.
        8. When it is set up, click save

        If you want to use the other tabs described in the field specific documentation, click on the Edit Field button (pencil). Edit the information and click save.

        Quick Edit

        The quick edit tab is used to create and edit your form. It is divided up into two areas, the toolbox, and the form table.

        The toolbox contains all of the available form fields for the form. It is divided into groups of field for ease of use.

        1. The first section is Basic Fields, This contains the less complicated fields that are used the most on forms. Things like checkbox, selection, text box.
        2. The second section, More Fields,  contains the more complicated and less used field types such as file, password, and rating scale.
        3. The next section is Fieldsets. This contains the begin and end markers for fieldsets.
        4. The last section, Actions, contains the actions available on submit for your form. These include mailer, and save data.

         

        The form table allows you to see a version of your form with editing, deleting, and ordering capabilities. Each field in the table has 3 columns, order, field, and edit/delete. The order column is used to drag the fields into a new position on the form. The field column displays the field and what it looks like. The Edit/Delete column has an edit button and a delete button for each field.

        Edit Button - The edit button will display all of the parameters available for the selected field.

        Delete Button - The delete button will remove the field from the form.

        Standard information for most form fields

        Most form fields ask for some standard information this is a description of these information requirements.

        Form fields require information to make them useable, The following information fields will appear on most dialogs for form fields.

        Default Tab

        1. Field Label - The field label is the label that will display on the form for this form field.(This is required)
        2. Field Help - The field help is an area where you can specify more detailed information about the form field.
        3. Required - The required check box allows you to mark a form field as required. An error will display if the submit button is clicked and this is not filled out.
        4. Default - The value the field will have when first loaded.

        Overrides Tab

        1. Default Expression - A TALES expression that will be evaluated when the form is displayed to get the field default value. Leave empty if unneeded. Your expression should evaluate as a string. PLEASE NOTE: errors in the evaluation of this expression will cause an error on form display.
        2. Custom Validator - A TALES expression that will be evaluated when the form is validated. Validate against 'value', which will contain the field input. Return False if valid; if not valid return a string error message. E.G., "python: test(value=='eggs', False, 'input must be eggs')" will require "eggs" for input. PLEASE NOTE: errors in the evaluation of this expression will cause an error on form display.
        3. Enabling Expression - A TALES expression that will be evaluated when the form is displayed to determine whether or not the field is enabled. Your expression should evaluate as True if the field should be included in the form, False if it should be omitted. Leave this expression field empty if unneeded: the field will be included. PLEASE NOTE: errors in the evaluation of this expression will cause an error on form display.

        (Form Field) Checkbox

        The check box field allows you to add a check box to the form.

        Default Tab

        1. Default - when this is checked, this check box will default to checked.
        2. Validator- This will check that the checkbox is in 1 of 3 states
          1. none - this is the same a choosing nothing (it is used mainly to turn off validation)
          2. is checked - This will give an error if the checkbox IS NOT checked.
          3. is not checked - This will give an error if the checkbox IS checked.
        3. True Display String - This is the value that will be displayed in a mailer email or in the save data adapter if the box is checked.
        4. False Display String - This is the value that will be displayed in a mailer or save data adapter if the box is not checked.

         

        (Form Field) Date/Time

        The date time field is used to collect Date and Time specific information. You can customize it so it will only ask for either Date or both Date and Time.

        Default Tab

        1. Default - This is the default value for the field when the form first opens.
        2. Show Time Selection Options - This checkbox will either show time selections on the form for this field or not. The default is to show time selections.
        3. Starting Year - The starting year is the first year available on the year drop down.
        4. Ending Year - The ending year is the last year on the year drop down
        5. Future Years To Display - This sets the number of years in the future to display on the year drop down. The Ending Year will override it.

        (Form Field) Decimal Number Field

        The Decimal Number Field allows the user to enter a number. The field can be set up to validate the number for maximum and minimum values.

        1. Default - This is the number that is displayed in the field when the form is first opened. This value can be overridden by the Default Expression override.
        2. Minimum Acceptable Value - This is the minimum value the field will accept.
        3. Maximum Acceptable Value - This is the maximum value the field will accept. (Required)
        4. Max Length - The maximum number of characters the user will be able to enter.
        5. Size - The size of the text entry box on the form in characters.

        (Form Field) File Field

        The file field allows the user to attach a file to the form.

        Maximum Upload Size (Megabytes) - This is the maximum allowable file size in Megabytes. Set this to 0 for no limit. NOTE: if you have a mailer set up this should be limited to 10 Megabytes.

        (Form Field) Lines

        This field appears as a text box. It allows the user to enter individual values on the form. One value per line.  This field can be used as a server side field for program interaction.

        Default Tab

        1. Hidden - This will make the field invisible to the end user. This is used if you are storing information for later use.
        2. Default - Enter any values in the field that you want displayed when the form is opened.
        3. Rows - This is the number of rows displayed in the text area.

        Overrides Tab

        Server-Side Variable - When checked, this field will act as a server side variable. This means it will only be available to the server and not the browser.

         

         

        (Form Field) Multi-Select

        The Multi-Select field allows you to put a multiple selection drop down or check boxes on your form. This is useful when the user can select several options but you want them to be listed in the same field.

        Default Tab

        1. Rows - This is the number of rows to display in the drop down.
        2. Options - Enter each option the user will have for the field on a separate line. If you want the value sent to be different than the value displayed enter the value sent first followed by a vertical bar (|) followed by the display value. ex. Robert Jones|Bob.
        3. Presentation Widget- Use this to switch between selection list (drop down) and check box list.

        Overrides Tab

        Options Vocabulary - This field will allow you to create a TALES expression that will generate the option list at page load.

        (Form Field) Password

        The password field is a special type of text box that obscures what the user is typing.  This is used for passwords, and private data.

        Default Tab

        1. Max Length - This is the maximum number of characters allowed in this field.
        2. Size - This is the  length of the text entry box in characters. If the max length is more it will scroll.

        (Form Field) Rating-Scale

        The rating scale field allows you to create a series of questions for the user to rate. The ratings can have any labels you want. Each question will have a radio button group (can select only one value) for each question with a button for each answer.

        Default Tab

        Note: there are no default values available for this field. The scale can be pre-populated by using a TALES expression in the overrides tab.

        1. Questions - Enter the questions, one per line, in this box. They will be displayed down the side of the scale.
        2. Answers - Enter all possible answers. These will be displayed across the top of the scale.

        (Form Field) RichText

        The rich text field allows the user to format the text they enter into it. It uses the Tiny MCE editor. This field is useful for Formatted text such as resumes or essays.

        Default Tab

        1. Rows - This is the number of rows the rich text field will provide before having to scroll.
        2. Max Length - This is the maximum number of characters the user can enter into the field. If you want no limit enter the number 0.

        (Form Field) Selection

        The Selection field allows the user to choose one of several options. When you create the field you can choose whether you want a radio button group or a selection list (drop down).

        Default Tab

        1. Options - Enter each option the user will have for the field on a separate line. If you want the value sent to be different than the value displayed enter the value sent first followed by a vertical bar (|) followed by the display value. ex. Robert Jones|Bob.
        2. Presentation Widget- Use this to switch between selection list (drop down) and check box list. You can also choose to let the system decide on load what kind of widget to use.

        (Form Field) String

        The string field is used for allowing users to enter unformatted text information into your form.

        Default Tab

        1. Hidden - This check box hides to field from the browser. Use this to enter information that the user doesn't need to see but you need on the form anyway. This can also be used to pass information from one form to another.
        2. Max Length - The maximum length in characters this field will accept.
        3. Size - The size of the text box in characters that will display on the screen.
        4. Validator - The validator has several options for checking the field for validity such as email address, phone number, or a postal code. The validator will show an error on the field and not allow the form to be submitted until the error is corrected.

        Overrides Tab

        Server-Side variable - Is only available from the server and is not displayed or sent to the browser. This can be useful for programming.

        (Form Field) Text

        The text field, also known as a text area, allows the user to enter multiple lines of un-formatted text into the form.  This can be useful for long answer questions or "Additional Information" fields.

        Default Tab

        1. Hidden - This allows you to hide the field from the browser so the user can not change it.
        2. Rows - This is the number of rows displayed in the text box area.
        3. Max Length - This is the maximum allowable characters in the field. Use 0 for no limit.
        4. Reject Text with Links? - Check this box to prevent people from adding links to this field.

        Override Tab

        Server-Side Variable - This check box allows you to use this field as a variable for programming on the server.

        (Form Field) Whole Number

        The whole number field is used to collect numeric information that must be an integer. If you need decimal numbers use the floating point field.

        Default Tab

        1. Minimum Acceptable Value - This is the lowest value this field will accept.
        2. Maximum Acceptable Value - This is the highest value this field will accept.
        3. Max Length - This is the maximum number of characters the user can enter into the field.
        4. Size - This is the length in characters of the text box on screen.

        Custom Script (Adapter)

        Advanced Users Only

        The custom script adapter allows you to write a python script to manipulate data on the form. Advanced users should be the only ones using this adapter because it can cause problems with your form or site if used incorrectly.

        Dafault Tab

        Proxy Role - The proxy role allows you to specify with what permissions on your site the script will run.

        Script Body - This is where you put your script.

        Mailer (Adapter)

        The mailer adapter allows you to create an email that will be sent on submission of the form. The email can go to the user filling out the form or to the person administering the form. You can create multiple mailers for different recipients. A mailer adapter is created when you create your form.

        Default Tab

        1. Recipient's full name - This is the full name of the recipient. It is a text string and can contain anything.
        2. Recipient's e-mail address - This is the email address for the forms recipient.

        Addressing Tab

        1. Extract Recipient From - This field allows you to designate the contents of a form field as the recipient address. This will override the recipient's address from the Default Tab.
        2. CC Recipients - The addresses in this field will receive a copy of the email. One address per line.
        3. BCC Recipients - The addresses in this field will receive a blind copy of the email. These addresses will not display to the other recipients. One Address per line.
        4. Extract Reply-To From - This field allows you to designate the contents of a form field as the reply-to address on the email.

        Message Tab

        1. Subject - This is a text field that will appear in the subject line of the email.
        2. Extract Subject From - This field allows you to designate the contents of a form field as the subject line in the email. This field will override the subject field.
        3. Body (prepended) - This is text that will appear at the beginning of the email. This can be used to explain the email or to thank the user for filling out the email.
        4. Body (appended) -  This fields contents will display at the end of the email.
        5. Body (signature) - The signature section will appear at the very end of the email.
        6. Include All Fields - If this is checked all fields in the form except labels and file fields will appear in the body of the email.
        7. Show Responses - This allows you to select specific fields from the form to include on the email. This will be ignored if the Include All Fields check box is checked.
        8. Include Empties - If this is checked the titles of empty fields will display in the email.

        Template Tab

        1. Mail-Body Template - This is the mail body template written in TAL. If you know TAL you can modify it otherwise don't change it.
        2. Mail-Body Type - This is the type of email the mailer will send.
          1. Text - will send a plain text email. This does not allow for any formatting.
          2. HTML - will send an email in HTML format. HTML format allows formatting of the email and the addition of images.
        3. HTTP Headers - Additional information the web server will pass on in the headers.
        4. Additional Headers - Any RFC822 headers compliant headers you want to add to your email.

        Encryption Tab

        1. Key-Id - Enter your encryption key in this field.

        Overrides Tab

        1. Subject Expression - The subject expression allows you to create the subject of the email with a TALES expression. This will override the subject field on the message tab.
        2. Sender Expression - This allows you to calculate the FROM field of the email based on a TALES expression.
        3. Recipient Expression - This allows you to calculate the recipient of the email based on a TALES expression. This will override the recipient from the default and addressing tabs
        4. BCC Expression - This allows you to calculate any BCC recipients of the email based on a TALES expression. This will override the BCC field on the Addressing Tab.

        Save Data (Adapter)

        The save data adapter is used to collect information from your form into a simple data structure. This data is not guaranteed to be available for long periods. It is recommended that you extract the data from the save data adapter weekly and save it in a spreadsheet.

        Usage: Once the save data adapter is set up and there is data you can go to it's URL and view or download the data by clicking on the "Click here to get the saved input " link. It is displayed in csv format which will open readily in excel. Once you have saved the data you can click on the "Clear Saved Input" button.  NOTE: This is permanent. It is very difficult to get your saved data back once you click this button. Some users create two save data adapters so they can only delete the data from one at a time.

        Default Tab

        1. Extra Data - This is extra information you can save to the adapter.
        2. Download Format - This allows you to create a CSV format data file or a tab delimited data file. The default is CSV.
        3. Include Column Names - This inserts the column names as the first row of data.

        Saved Data Tab

        This tab allows you to examine the saved data in the web browser.  This can be changed but it is not recommended.