Chapter Eleven

Configuring the Search Builder

Tango Search Builder Options and Setup

The Search Builder builds a series of actions that allows you to create Web forms that can be used to search a database, display the results of the search, and view, update, and delete individual records.

The topics covered in this chapter include:

setting search, record list, and record detail options
formatting the search form, and record list and record detail Web pages
customizing your Web forms and pages, and creating response messages
tips on modifying how the Search Builder builds actions
defining joins.

[back to top]

About the Search Builder

Using the Search Builder, you can quickly and easily build the actions necessary to:

display a form allowing users to specify search criteria
display a list of matching records
allow viewing of detailed information on a single record
allow editing and deleting of the records found.

Based on the settings in each of the option groups and the actions generated, the following is an example of what users might see in their Web browsers:

Web browser showing Search Builder 1

On the search form, the user enters the criteria for the records to return.
By default, a Begins with search is performed on text columns and an = (equals) search on all others. If desired, you can instead let users select each search operator from a pop-up menu.

To initiate the search, the user clicks Find.

Tango Server searches the data source for records matching the user's criteria and displays them on the record list Web page.

Web browser showing Search Builder 2

For more information, see "Configuring Tango Server".

Note: Character data from non-FileMaker Pro data sources is by default stripped of trailing spaces. You can disable this feature by using the configuration variable stripChars: assign the variable the value false in local scope for a particular application file, or, if you want to set the variable for all data sources, use the Tango 2000 Configuration Manager (the config.taf application file) to change the variable's value to false in system scope.

If you want, you can configure the Search Builder to display Next and Previous buttons for paging through large result sets.

To view detailed information for a record, the user clicks the name of the record in the list, which is hot linked to the record detail.

The record detail Web page displays more information on the selected record and--if you allow it--lets the user edit or delete it.

When you open the Search Builder window it contains three main groups of options you can specify: Search, Record List, and Record Detail:

Search. Specify the columns you want users to search and define the format of the search form you want users to see in their Web browsers.
Record List. Specify the columns you want to display in the record list returned to the user after a search and define the format of the record list Web page.
Record Detail. Specify the columns you want to include on the single-record display Web page, which appears after a user clicks a specific record in the record list, and define the format of the record detail Web page. You can also set up the record detail Web page to allow users to delete the record and/or edit specified columns.

To switch among option groups, click the appropriate tab in the Search Builder window.

[back to top]

Setting Search Options

When you drag the Search Builder icon from the Actions palette into an application file, the Search Builder window opens, displaying the Search options window.

You use the search options to define the appearance of the search form, which columns the user can search on, and how the values entered by the user are used to search the database. You can also define fixed criteria in addition to the ones the user enters.

Tip: You can save your Tango Builder page formats to use for new tables you create in the Builders. For more information, see "Page Format Table Settings".

Search Columns List

Drag columns from the Data Sources Workspace to this list to use them in defining the search. Columns in the Search Columns list appear in the format table_name.column_name. The order of the columns in the Search Columns list determines the order of the fields on the resulting search form.

The following table describes the operations you can perform on columns:

To ...	Do This ...
Reorder columns	Select the columns and drag them to a different location in the list.
Delete columns	Select the columns. Choose Clear from the Edit menu, or press Delete on the keyboard.
Delete columns without confirmation	Hold down the option key while using the Clear or Delete command.

Column Options

Use the Column Options section of the Search window to configure each search column. You can specify how each column's entry field appears on the search form and how the value entered by the user is used to search the database.

Column options

Field Title

In Field Title, set the title of the value entry field for the column as you want it to appear on the search form.

Operator

Use this option to set the search operator for the column. For example, if the operator is set to Begins with, Tango searches the database for records that begin with the column's search value. If you select User Enters, the search form displays a pop-up menu of the operators available, and the user can select which operator to use.

User Enters Value

Select this option if you want the user to enter a value in an entry field on the search form. The available field types are: Text, Pop-up Menu, Selection List, Checkbox, and Radio Buttons.

Field Type

To select a value entry field type for a column, select the column in the Search Columns list and then an item from the Field Type pop-up menu.

You can edit a field's values at any time by clicking the Field Properties button in the Search Builder window or by choosing Field Properties from the Attributes menu.

The following describes each of the options in the Field Properties dialog box for each field type:

Text. Use the Text field type to provide single- or multi-line entry of values.

Default Value is the default value you want to appear on the new record entry form.

Maximum Length is the maximum number of characters the user can enter in the field. This option is not available when Scrolling Field is selected because HTML does not support it.

Width is the width of the field in characters.

Height is the number of lines of text displayed in the field without scrolling. This field is available only when you select Scrolling Field.

Scrolling Field. Select this option if you want a multi-line text entry field with a scroll bar.

Password Field. Selecting this option generate form input elements with the attribute TYPE=PASSWORD, which conceals the characters that the user enters into the text field (for example, often asterisks or bullets are shown).
Pop-up Menu, Selection List, and Radio Buttons. Each of these field types lets the user select the search value from a predefined list.

Pop-up Menu

Selection List

Radio Buttons

For example:

Use the Field Properties dialog box for these field types to specify the values and choose the default. The same dialog box appears for all three field types.

To add an item to the values list

From the Field Type pop-up menu, select Pop-up Menu, Selection List, or Radio Buttons; then do one of the following:
- In the Search window, click the Field Properties icon.
- From the Attributes menu, choose Field Properties.
The Field Properties dialog box for the selected column appears.
Choose Add.

An "Untitled" entry appears:
Type a name in the Name field.
Press Tab to copy the name into the Value field, or enter a value for the item if you want it to be different from the name.
Click Add to continue adding items to the values list.

When you have added all of your items to the values list, click OK.

The Name determines what the user sees for this item. The Value determines what is used as the search value. If your database column uses abbreviations or codes for values, you can enter a more user-friendly value into the Name field and the actual value in the Value field. For example, if you are creating a field to search a "state" database column containing abbreviations such as "CA", "NY", and "GA", you can use these values in the list items' Value fields, and the full state names ("California", "New York", and "Georgia") in the Name fields.

The following table lists the other operations you can perform on the values list:

To ...	Do This ...
Set which item will be initially selected	Select an item in the list and choose the Selected option. The item then appears in bold in the list. If you do not specify an item as Selected, the user's Web browser determines which item is initially selected. Most Web browsers choose the first item, but some do not select any in this case.
Delete an item	Select it in the list, and click Delete. To delete without displaying a confirmation dialog box, hold down the option key while deleting.
Copy list items from one field's value list to another's	Select the items in the list, choose Copy from the Edit menu, and close the dialog box. Select another column to which you have assigned a values list-type field (Pop-up Menu, Selection List or Radio Buttons). Click the values list and choose Paste from the Edit menu. This procedure is useful for copying a list for a particular column to and from the Record Detail window of the Search Builder (as well as the New Record Builder).
Create an item that causes the column to be omitted from the search criteria when chosen	Leave the Value field for that item empty and make sure the Include criteria if value is empty option is not selected.

Checkbox. The Checkbox field type lets the user select between an empty search value (unchecked) and a value you specify (checked).

Checked Value is the value to be used for the search if the checkbox is selected by the user. If the checkbox is not selected, an empty value is used.

Initially Checked specifies whether the checkbox should be checked by default.

Fixed Value

When this option is selected, the search value is hard-coded and no entry field appears on the search form. The value you specify is used for every search.

For more information, see "Field Type".

Using the Value pop-up menu, select one of the following options for a fixed value:

Value Entered. Use the text box provided to enter the search value for the column.
SQL Expression. The value returned by the SQL expression text entered is used as the search value. The text entered is evaluated by the database, and the result is used as the search value.

Note: For ODBC data sources, you can enter ODBC scalar functions here.

SQL Statement. The SQL statement entered is executed, the results retrieved, and the first data item of the results is used as the search value. For example, if you enter:

SELECT MAX (cust_num) FROM customer

the largest customer number is used as the search value.

Note: The SQL Expression and SQL Statement values are not available when using a FileMaker Pro data source.
Current Timestamp. The current timestamp (date and time combined) on the Tango Server computer is used as the search value.
Current Date. The current date on the Tango Server computer is used as the search value.
Current Time. The current time on the Tango Server computer is used as the search value.

For more information on what the CGI parameters evaluate to, see "<@CGIPARAM>" in the Meta Tags and Configuration Variables manual.

CGI Parameters. The rest of the fixed value options are referred to collectively as CGI parameters. They include Client Name, Client Domain, Client Domain Name, Client IP Address, Client Browser, Server Address, Server Port, Referer Page URL, Method and Full Request. They are passed by either the user's Web browser or the Web server with each request to Tango. When you specify one of these parameters as the search value, the parameter value used is the one passed in when the user clicks Find.

Summary: Setting Column Options

The following table describes the settings you can make in the Column Options section of the Search window:

To ...	Do This ...
Let the user specify the search value for a column	Select the column in the Search Columns list. Select the User enters value radio button. This option defines the column as a user-searchable field, and a value entry field will appear on the search form.
Specify the title to appear for a column's search form value entry field	Select the column in the Search Columns list. The column's name appears in the Field Title field. Replace the name with the desired field title. Tango remembers the entered title and uses it as the default the next time you use the column.
Specify the type of value entry field to be displayed for a column	Select the column in the Search Columns list. Make sure the User enters value option is selected. From the Field Type pop-up menu, select the type of field you want displayed. A Value dialog box appears, allowing you to specify the field attributes.
Include a column in the search even if the user leaves its value entry field empty	Select the column in the Search Columns list. Select the Include criteria if value is empty option. If the user leaves this column's value empty and clicks Find, only records that have an empty value in the column are returned. If the option is not selected (the default), the column is omitted from the search when the user does not enter a value.
Specify the operator Tango uses when comparing the database column values with the search value	Select the column in the Search Columns list. From the Operator pop-up menu, select the operator that specifies how you would like the column searched. For example, Begins with searches for values that begin with the entered value.
Let the user select the search operator for a column	Select the column in the Search Columns list. Select User Enters from the Operator pop-up menu. A pop-up menu of available operators appears beside the column's value entry field on the search form.
Hard-code the search value for a column	Select the column in the Search Columns list. Select the Fixed value option. From the Value pop-up menu, select a search value. You can use one of the preset values, such as current date or time, select Value Entered to enter a value yourself, select one of the SQL options to get a search value from the data source, or select a CGI parameter. Columns specified as Fixed value do not appear on the search form.

[back to top]

Formatting the Search Web Page

Use the format options to define how the search fields and their titles display.

To change the format of the search Web page

Do one of the following:

In the Search window, click the Page Format icon.
From the Attributes menu, choose Page Format.

The Page Format dialog box appears.

Specify the table attributes as follows:

Border width. The width of the table border in pixels. Select none, or from numbers 1 to 8.
Border color. The color of the table border. Select default or a color from the list.

Note: For Border color, Background color, Cell spacing, and Cell padding, selecting default instead of a value omits that attribute from the HTML and causes the Web browser's default setting to be used instead.
Background color. The background of the table. Select default or a color from the list.
Cell spacing. The amount of space, in pixels, inserted between individual cells in the table. Select none, or from numbers 1 to 8.
Cell padding. The amount of space, in pixels, between the border of a cell and the contents of the cell. Select none, or from numbers 1 to 8.

[back to top]

Customizing Your Search Form and Result Messages

Header, Footer, and No Results HTML

Use Header HTML and Footer HTML to customize the search form by specifying HTML to appear above and below the search form.

No Results HTML lets you specify the HTML to return when no records match the search criteria specified by the user.

To enter Header HTML, Footer HTML, or No Results HTML

Do one of the following:
- In the Search window, click the Header HTML, Footer HTML, or No Results HTML icon.
- From the Attributes menu, choose Header HTML, Footer HTML, or No Results HTML.
The corresponding HTML editing window appears:

You can switch between the HTML editing windows by clicking on the Header, Footer, and No Results tabs at the top of the HTML window.
Enter the HTML you want.
Close the editing window.

Changing Button Titles

The search form contains two buttons below your search fields:

The Find button initiates the search.
The Reset Values button resets the entry fields to their default values.

To change button titles

Do one of the following:
- Click the Button Titles icon.
- From the Attributes menu, choose Button Titles.
The Button Titles dialog box appears.
Enter new titles in the corresponding fields.
Click OK.

[back to top]

Setting Record List Options

Use the options in the Record List window of the Search Builder to define the appearance and functionality of the Web page returned after the search (defined in the Search section) is performed.

Among other things, you can specify:

which columns from each matching record are displayed
the ordering of result records
the maximum number of records to be returned
whether you want Next and Previous buttons to appear, allowing paging through large result sets
which column or columns appear as links to the detail Web page.

Display Columns

Drag columns from the Data Sources Workspace to this list to have them retrieved from the database and displayed on the record list Web page. The order in which columns appear in the Display Columns list determines their order on the Web page.

Container Fields

FileMaker Pro

FileMaker Pro data sources only: Container fields can be dragged into the Record List and Record Detail lists, allowing you to display PICT, GIF, and JPEG pictures in the record list.

Note: The Container field must contain a pasted-in picture, not a file reference. Container fields containing other types of data are not supported.

In the Record List and Record Detail, only the Field Title and Display As fields in the Column Options are enabled for a container field.

When Tango retrieves the field data from FileMaker Pro, it converts it to JPEG format. Apple's QuickTime software is used to perform the conversion from PICT to JPEG data, so QuickTime (2.0 or later) must be installed on the Tango Server machine.

For the picture to display properly, the user's Web browser must support inline JPEGs.

Memory Considerations

For more information, see "Configuring Tango Server"..

For more information, see "itemBufferSize" in the Meta Tags and Configuration Variables manual.

By default, Tango is limited to retrieving a maximum of 64K of data from a single field. This is usually more than enough for most fields, but may not be adequate to handle some images. You can increase the maximum supported field size using the config.taf and assign a larger value to the itemBufferSize system configuration variable.

Retrieval of very large pictures from FileMaker Pro may require increasing the memory allocated to both the Tango CGI or Web server and the FileMaker Pro application.

Performance Considerations

Including a Container field in the record list can adversely affect the speed at which the page is displayed. This is because a separate request must be made by the Web browser for each picture. Each of these requests involves a Tango application file execution and a FileMaker Pro search. For example, if you include one Container field in your record list and a user's search returns 20 records, 21 separate requests must be made in order to display the record list page--one for the text of the page and one for each picture.

To ensure reasonable performance, you should keep the size of pictures displayed on the record list page to a minimum and limit the number of records displayed; see "Maximum Matches".

Order By

Records from the database are sorted on the record list Web page according to the order specified in the Order By list. You can drag any number of columns into this list; however, each of the columns must also appear in the Display Columns list.

The records are sorted by the first column listed. Then, records having the same values in that column are ordered by the second column, and so on. The default sort order is ascending, meaning records with lower values in the sort column appear first in the list. You can toggle between ascending and descending by clicking the and icons.

FileMaker Pro

Note: Container fields (FileMaker Pro data sources only) are not allowed in the Order By list.