An Autofill Handler maps a form to its corresponding Autofill Query and Data Source, connecting all the components together to enable the Autofill process. When invoked, the Autofill Handler uses its Data Source to connect to the external database, retrieves data from the database using its Autofill Query, and finally places the retrieved data into the form. An Autofill Handler determines the behavior of an Autofill operation.
The final step in setting up a form for automatic population from a database is uploading an Autofill-designed form into the Formatta E-Forms Manager catalog and configuring one or more Autofill Handlers.
In the Autofill Handlers section of the Autofill tab, click the New Autofill Handler link. This will launch a wizard where you will set up the first Autofill Handler for the form. The screens of the Autofill Configuration Wizard will prompt your for basic information about the handler. Navigate through the wizard using the Next, Back and Cancel buttons. Use the fields as described below.
Complete the fields in this screen, then click the Next button to continue. This screen prompts you for the following data:
Handler Name: The unique name for this handler. You may wish to have the name refer to the data source, query, or form in some way for identification. For most Autofill operations, you will refer to the handler by this name in the design of your form where you want it to be invoked.
Action Type: Specifies the distinct method by which the form utilizes Form Autofill, depending on the nature of the application. Click the radio button corresponding to one of the following:
On Download: Specifies that this handler will pre-populate fields of the form with data from a database upon download from the Formatta E-Forms Manager catalog. Data retrieved from the database can be applied to one or more standard fields in the form, or can be placed as options in a drop-down list box field. This type of Autofill requires no interaction from the form user, and makes data available in the form as soon as it is presented to the user.
Remote Command: Specifies that the Autofill Handler will be called from a Remote Command in the form. A remote command may be called from the click of an action button, update of a field value, printing the form, etc. When a form event is triggered that has an Autofill Remote command associated with it, the form then connects to Formatta E-Forms Manager remotely, where it retrieves data from the database and populates the appropriate fields of the form. The user may optionally be presented with a means of choosing a particular data set retrieved prior to form field population.
Autofill Type: Formatta E-forms configured for Form Autofill can populate form fields in a variety of ways. Click the radio button corresponding to one of the following:
Direct-to-Form: This type of Autofill can be invoked upon form download or from a Remote Command. With this type, data retrieved from an Autofill query is placed directly into specific fields on the form without prompting the user to choose from a list of data set options.
Listbox Field: This Autofill type can be invoked upon form download or from a Remote command. It can be used to populate a dropdown list box (combo box) field on the form from the database. This allows the choices in drop-down lists to be populated dynamically as an alternative to having them built into the form design.
Pop-up List: With this Autofill type, a query is run against the database, and any records found are presented to the form user in a summary format on a pop-up list window. This allows the form user to choose from a list of records found. When the user clicks on an item in the pop-up list, one or more fields in the form are automatically populated with data elements corresponding to the record selected.
Note: A pop-up list can only be used in an Autofill Handler with a Remote Command action type.
Authentication: Checking the Require Client Authentication checkbox forces a user of the form to successfully authenticate against a configured authentication scheme before the Autofill operation can be performed. If you want the Autofill operation to require authentication, check this box then choose the authentication scheme that you want to be used for the operation. You may explicitly specify any schemes that have been configured, or choose the "Always Use Default" option if you want the Autofill operation's authentication to always check against whatever scheme is designated as the default scheme. If the Autofill Type of the handler is "On Download", then this field is disabled.
Report No Results: With this checkbox you may specify whether you want Formatta E-Forms Manager to display a message to the user in a pop-up dialog if no query results were found by the Autofill operation. If you leave this checked, then the message that you specify in the following field (No Results Message) will be displayed when no query results are found.
No Results Message: If the Report No Results checkbox is checked, you may enter a customized message into this field that will displayed to the form user when the Autofill handler fails to find any data.
On the second screen of the Autofill Configuration Wizard, you must specify the Data Source and the Autofill Query that will be used by the Handler. The Data Source you select will determine which database the Handler will connect to, and the Query determines the result set that will be returned for form population.
The list of Autofill Queries displayed here will only show query definitions with result set types that are appropriate to the type of Autofill you chose on the previous screen. For example, if on the previous screen you specified a Direct-to-Form Autofill type, then only queries that are defined as returning a single record will be shown in the Autofill Query list.
If chose a Listbox Field or Pop-up List Autofill type on the first screen, then you will see this screen, which prompts you for additional information that is specific to the Autofill type. Below are descriptions of each:
If you chose "Listbox Field" as the Autofill Type, you need to specify the name of the form field that will be populated with list contents from the database. The field you choose must be a combo box field type in the form.
Column: Choose one of data elements from the query results to use as the value displayed in the choice list. This should be a single value that will allow the end user to uniquely and easily identify each record.
Title: Enter a value that will be used as the title for the pop-up window.
Message: Here you may enter a customized message that will be displayed above the list of results in the pop-up window. Here you may use the $RECORD_COUNT token, which will be replaced by the actual number of results that were found by the query.
If you chose the "Direct-to-Form" or "Popup List" type of Autofill, the final screen of the Autofill Configuration Wizard will prompt you to map columns from your query to fields in the form.
The following information may be helpful when using this screen:
You are not required to map every query column to a form field, but you must map at least one.
If you have specified default mappings in your Autofill Query Setup, the default values will already show as mapped. You may remove or change these mappings on this screen if you wish.
If the name of a column from your query matches a form field name, the mapping will be made automatically. You may remove or change these mappings on this screen if you wish. This type of default mapping is only made when you are creating an Autofill Handler, and not when editing an existing one. This pre-mapping is performed for any form field / query column combination whose names match. The comparison ignores case, spaces, and underscore characters.
To create the mapping of SQL query results to form fields on this screen:
Select a SQL query result column from the Query Columns list on the left.
Select a form field from the Form Fields list on the right.
By following the three steps above, a mapping will be placed into the list on the lower half of the screen. To remove a mapping from this list, you may click the Delete icon in the row you wish to delete. This will place the mapped form field back into the list so that it may be re-mapped if you wish.
If the Autofill Query chosen in the second screen is Multiple-Repeating results Autofill Query, and the form contains a Table control (or otherwise specially-named group of fields), the Form Fields list in this section will show field names with the # symbol at the end. This indicates that each item in the list represents a whole set of fields that can be mapped to for tabular Autofill. For more information on this, see Using Autofill for Tabular Data.
Once you have set up your Autofill Handlers, you need to enable them for your form. After closing the Autofill Configuration Wizard, you will return to the Autofill Tab of the Form Management Properties under the Catalog tab.
1. In the General Settings section, check the Enable Autofill box.
2. Click the Save Changes button.
3. In the Autofill Handlers section, check the box next to the handler you wish to use.
4. Click the Enable Selected button.
5. To disable a handler at any time, check the box next to the handler you wish to disable and click the Disable Selected button.
Once you are finished configuring your Autofill Handlers, you will be ready to use Designer to define field sets and add handler calls to your form.
