[TOC] [Prev] [Next] [Bottom]


Chapter Ten

Configuring the New Record Builder

Tango New Record Builder Options and Setup

The New Record Builder builds a series of actions that allows users to add a record to a database. For the new record, you specify the database columns the user can add data to and the result message to return after the record is added. Tango does the rest.

The topics covered in this chapter include:

  • setting new record column options
  • formatting the new record form
  • customizing your form and creating result messages
  • a summary of how to set column options.
[top] [back to top]

About the New Record Builder

You use the New Record Builder to build actions that, when Tango Server executes them, display a form allowing users to enter data for a new record and return a result message after the record is added to the database.

The user enters the values for the columns in the new record, and clicks Save to save the record. Tango Server saves the record to the data source and returns the HTML response you specified in the New Record Response HTML.

[top] [back to top]

Setting New Record Options
When you drag the New Record Builder icon from the Actions bar into an application file, the New Record Builder window appears.

All the options necessary for configuring the New Record Builder appear in its options window.

Columns

The columns you include in this list are the columns the user assigns values to in the new record. To add columns to the list, drag them from the Data Sources Workspace. Columns appear in the format table_name.column_name. You can only add columns from one table. The order in which the columns appear in the Columns list determines their order on the resulting new record entry 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.

Columns Options

Use the Column Options area to configure each column appearing in the Columns list. You can specify how each column's entry field appears on the new record entry form and whether a value is required for it or not.

Field Title

In this field, set the title of the value entry field for the column as you want it to appear on the new record entry form.

User Enters Value

Select this option if you want the user to enter a value in an entry field on the new record entry form.

Field Type

To select a value entry field type for a column, select the column in the Columns list and select an item from the Field Type drop-down list (Text, Drop-down List, List Box, Check Box, or Radio Buttons).

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

You can edit a field's properties at any time by clicking the Field Properties icon in the New Record Builder window or by choosing Field Properties from the Attributes menu. The Field Properties dialog box for the specified type of field appears. For example, in the case of a text field:

For more details on the different types of field that can appear here (text, drop-down list, list box, check box, or radio buttons), see "Field Type".

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

  • 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.
Fixed Value

If you select this option, no entry field appears on the new record entry form. The value you specify is used for every new record. 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 value for the Field Title.
  • SQL Expression. The value returned by the SQL expression text entered is used as the value. The text entered is evaluated by the database and the result is used as the column value in the new record.

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

  • SQL Statement. The SQL statement entered is executed, the results are retrieved, and the first data item of the results is used as the column value in the new record. For example, if you enter:

    SELECT (MAX (cust_num)+1) FROM customer

    the largest customer number plus one is used as the value for the column in the new record.

  • Current Timestamp. The current timestamp (date and time combined) on the Tango Server computer is used as the value.
  • Current Date. The current date on the Tango Server computer is used as the value.
  • Current Time. The current time on the Tango Server computer is used as the value.

For more information on what the CGI parameters evaluate to, see "Assigning Variables With the Assign Action", and "<@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 IP Address, Client Browser, Server Address, Server Port, Referer Page URL, and Method. When you specify one of these parameters as the column value, the parameter value passed in when the user clicks the Save button is used.
Required

Select this column option to prevent a record from being added, unless the user enters a value. If the user tries to leave the value field empty, an error message is returned.

If you select Fixed Value for the column, the Required option is not available. It is also not available for columns configured to use the Check Box field type. This is because a check box can have only two values: empty and the one you specify in the Field Properties dialog box. Making it required would mean the record could not be added unless the user checks the checkbox, in which case you could use the Fixed Value option for the column and have it not appear on the Web page.

Summary: Setting Column Options

The following table summarizes how to set column options for the New Record Builder.

To ...

Do This ...

Let the user specify the value for a column

Select the column in the Columns list. Select the User Enters Value option. This option defines the column as a user-enterable field, and a value entry field appears on the new record entry form.

Specify the title to appear for a column's new record form value entry field

Select the column in the Columns list. The column's name appears in the Field Title field. Replace the text with the desired field title. Tango remembers the entered title and uses it as the default the next time you choose it.

Specify the type of value entry field you want to display for a column

Select the column in the 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 to display. A dialog box appears allowing you to specify the field attributes.

Prevent the user from omitting a column value

Select the column in the Columns list. Make sure the User Enters Value is selected. Select the Required option. If the user leaves the field empty and tries to save the record, an error message appears explaining the problem.

Hard-code the value for a column

Select the column in the Columns list. Select the Fixed Value option. From the Value drop-down list, select a value to use for the new record. You can use one of the preset values, such as Current Date or Current Time, or select Value Entered to enter a value yourself. Select one of the SQL options to get a value from the data source. Columns specified as Fixed Value do not appear on the new record entry form.

[top] [back to top]

Formatting the New Record Form

Use the format options to determine the layout method to display the value entry fields and their titles.

To change the page format options of the new record form
Do either of the following:
  • In the New Record Builder 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 1 to 8. The default none has a value of zero.
  • 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 (which tells the browser to use its default setting 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 1 to 8.
  • Cell padding. The amount of space, in pixels, between the border of a cell and its contents. Select none, or from 1 to 8.
[top] [back to top]

Customizing Your Form and Creating Result Messages

The Snippets Workspace includes the default builder HTML snippets described in this section. They include snippets for Form Header, Form Footer, and New Record Response.

Header, Footer, and New Record Response HTML

You use Header HTML and Footer HTML to customize the new record entry form by specifying HTML that is placed above and below the entry form.

The New Record Response HTML is returned after the user saves the new record.

The Column Snippets folder in the Snippets Workspace contains the names of all the columns in the table being inserted into. Dragging a column name to the HTML editing field causes an <@COLUMN> tag to be added to the HTML. When the application file is executed, the column's value in the new record is included at that location in the response.

To display values from the new record, Tango must be able to get those values from one of three places: the new record form submitted by the user, a fixed value you have specified, or from the database. If you include a column in the result message that does not appear in the Columns list of the New Record Builder window, Tango must do a search of the database to retrieve the new record after it is added.

To do so, Tango must have the value of the record's primary key column(s). This means the primary key column(s) must appear in the Columns list of the builder. Without this information, Tango Editor does not permit you to build the New Record actions.

To enter Header HTML, Footer HTML, or New Record Response HTML
  1. Do either of the following:
    • In the New Record Builder window, click the Header HTML, Footer HTML or New Record Response HTML icon.
    • In the main window, choose Header HTML, Footer HTML, or New Record Response HTML from the Attributes menu.

    The corresponding HTML editing window appears.

  2. If you want to include HTML other than the default snippets, enter it.
  3. Close the editing window.

Changing Button Titles

The new record entry form contains two buttons at the bottom of your form:

  • The Save button saves the record.
  • The Reset Values button resets the entry fields to their default values.
To change button titles
  1. Do either of the following:
    • In the New Record Builder window, click the Button Titles icon.
    • In the main window, choose Button Titles from the Attributes menu.

    The Button Titles dialog box appears.

  2. Enter new titles in the corresponding fields.
  3. Click OK.

Actions Built by the New Record Builder

The actions built by the New Record Builder appear in the application file window.

For more information, see "Building the Actions".

The following shows the actions resulting from the New Record Builder process and the conditions under which the actions are built:

IfForm

<@ARG _function> = form

This section appears only if one or more user-enterable fields exist.

Form

ElseIfInsert

<@ARG _function> = insert

If no form is present, this is an If action named IfInsert.

IfMissingRequiredFields

This action contains one criterion for each required field, checking to see if <@ARG fieldName> is empty. All the criteria are OR'd.

If there are no required fields, this If/Else condition does not exist.

MissingFieldsMessage

If the user leaves out values for required fields, the HTML for this action displays the following message:

Error: Missing Required Fields

The record could not be added because the following required fields were left empty:

...

Please go back and enter values for these fields.

ElseDoInsert

Insert

If you selected SQL Statement for any column value, a Direct DBMS action (one for each) appears immediately before the Insert action.

InsertResponse

For information about the new record entry response, see "Header, Footer, and New Record Response HTML".

ElseError

Invalid Function

The HTML for this action displays the following message:

Error: Invalid Function

An unknown function was specified.

Return

HTML Snippets

The Snippets Workspace contains a snippets folder named Builder Snippets, and a subfolder named New Record. The New Record folder contains snippets for the Form Header, Form Footer, and New Record Response.

The New Record Builder uses these snippets in the designated places as default values for the named attributes.


[TOC] [Prev] [Next] [Bottom]


docs@pervasive.com

Copyright © 1998, Pervasive Software Inc. All rights reserved.