Chapter Nine

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 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 are examples of what users might see in their Web browsers.

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 drop-down list.

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 page.

For more information, see "Configuring Tango Server".

Note: Character data from 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 config.taf application file to change the variable's value to false in system scope.

If desired, 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 text, linked to the record detail.

The record detail 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 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 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 bar 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.

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 Delete from the Edit menu, press the Delete key on the keyboard, or select the Delete Selected Items icon on the toolbar.
Delete columns without confirmation	Hold down the Ctrl key while using the 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.

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 drop-down list 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, Drop-down List, List Box, Check Box, and Radio Buttons.

Field Type

To select a value entry field type for a column, select the column in the Search Columns list and select an item from the Field Type drop-down list.

A Field Properties dialog box appears allowing you to specify values for the field.

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. The height of a non-scrolling field is always "1".

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

Drop-down List, List Box, and Radio Buttons. Each of these field types lets the user select the search value from a predefined list.

Drop-down List
List Box
Radio Buttons

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

Do either of the following:
- In the Search window, click the Field Properties icon.
- In the main window, choose Field Properties from the Attributes menu.
The Field Properties dialog box for the selected column appears.
Choose New.
An "Untitled" entry appears.
Type a name in the Name field.
Press the Tab key 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 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 theName 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 browser determines which item is initially selected. Most browsers choose the first item, but some will choose none 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 Ctrl 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 (drop-down list, list box, or radio buttons) and click the Field Properties icon. 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.

Check Box. The Check Box 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 check box is selected by the user. If the check box is not selected, an empty value is used.

Initially Checked specifies whether the check box 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 drop-down list, 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.
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 Password, Client IP Address, Client Browser, Server Address, Server Port, Referer Page URL, and Method. 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 drop-down list, 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 drop-down list, 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 drop-down list. A drop-down list 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 drop-down list, 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 Page

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

To change the format of the search page

Do either of the following to change these options:

In the Search window, click the Page Format icon.
In the main window, choose Page Format from the Attributes menu.
The Page Format dialog box appears.

Tango aligns the page fields using an HTML table. 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 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 Creating 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 either of the following:
- In the Search window, click the Header HTML, Footer HTML, or No Results HTML icon.
- In the main window, from the Attributes menu, choose Header HTML, or Footer HTML, or choose Responses then No Results HTML from the submenu.
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 bottom of the HTML window.
Enter the desired HTML.
Close the editing window.

Changing Button Titles

The search form contains two buttons below your search fields:

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

To change button titles

Do either 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 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.

Order By

Records from the database are sorted on the record list 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.