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



Chapter Eleven

Using Actions


The Basics of Using Tango Actions

A Tango application file is made up of a series of one or more actions. Each action performs a specific type of function and can have results, usually in the form of HTML1, associated with it. The applications you create may be used to input data to information systems, compose and display information from data sources, and many more interactions.

When an application file is called, the actions in it are executed by Tango Server. When execution is complete, the HTML results are returned to the user's browser. These results can be from the user or from interaction with other servers, normally DBMSs.

Several actions allow you to search, add, update and delete database records. There are also actions for executing manually entered database statements and controlling the flow of execution within an application file. You can also automatically create a sequence of actions using the builders.

This chapter covers the following topics:

  • the Actions bar
  • working with actions
  • assigning attributes to actions.
[top] [back to top]


About Actions

The Actions bar shows all the available action types. It appears whenever an application file is active, or you choose Actions Bar from the View menu.


!Tip: You can drag the Actions bar to anywhere on your desktop and resize it.


You add all Tango actions to an application file from the Actions bar.

The following table lists each action, its function, and where in this User's Guide you can find more information.

Icon

Action

Function

User's Guide Reference

Select

Selects actions in the application file window.

This chapter.

Search

Retrieves records from a database.

"Searching a Database"

Insert

Adds records to a database.

"Adding Records to a Database"

Update

Changes records in a database.

"Modifying a Database Record"

Delete

Removes records from a database.

"Removing a Database Record"

Direct DBMS

Executes SQL statements.

"Executing SQL"

Begin Transaction, End Transaction

Begins a transaction and ends a transaction with a rollback or commit.

"Creating Database Transactions"

Results

Performs no special functions of its own, but it lets you append HTML to the results.

This chapter.

Mail

Sends out electronic mail.

"Sending Electronic Mail From Tango"

File

Reads, writes, and deletes files on the Tango Server machine.

"Reading, Writing, and Deleting Files"

Script

Allows you to specify server-side JavaScript code to execute.

"Executing JavaScript"

External

Calls an external code module to perform a function and return results.

"Using an External Action"

Assign

Makes specified value assignments.

"Assigning Variables With the Assign Action"

Group

Groups related actions.

"Grouping Actions"

If, Else If, Else

Executes an expression and based on the result of the expression affects the control flow in the application file.

"Conditional Action Execution (If Action)"

While Loop, For Loop

Repeats a set of contained actions: until an expression evaluates to true or for a specified number of times.

"Repeating Actions (Loop Actions)"

Break

Terminates processing in a loop.

"Exiting a Loop (Break Action)"

Branch

Causes a jump to another action or action group.

"Jumping to a Designated Action (Branch Action)"

Return

Ends execution of the application file and returns the accumulated Results HTML to the Web browser.

"Ending File Processing (Return Action)"

As well as actions, the Actions bar includes icons for the Search Builder and the New Record Builder. You add the builders to an application file in exactly the same way you add actions.

Icon

Builder

Function

User's Guide Reference

Search Builder

Builds the actions required to perform a search.

"Configuring the Search Builder"

New Record Builder

Builds the actions required to add a new record.

"Configuring the New Record Builder"

[top] [back to top]


Working With Actions

The application file window shows the actions that you want Tango Server to execute. Generally speaking, actions are executed sequentially, from top to bottom, until a control action is encountered. Control actions make decisions and cause execution to jump to another action or action group.

An icon indicates the type of action, and each action must have a name.


!Note: Each action name in the application file must be unique.


An action can also have attributes. Once assigned, action attribute icons appear beside the action name in the Attributes column indicating which actions have what attributes associated with them.

Database operations in the application file operate on the data source each is assigned to.

Adding an Action

To add an action to an application file

Do either of the following:

  • Drag an action icon from the Actions bar into the application file window (the cursor changes to include crosshairs and the action icon you are adding), and drop it where you want to add the action.
  • Click an action icon, move the cursor into the application file window (the cursor changes to crosshairs), and click where you want to add the action.

In either method, a gray line indicates where the new action is to be placed.

If the action has an editing window, it opens automatically.


!Tip: To prevent the action's editing window from being opened automatically, hold down the Ctrl key while dragging the new action into the document window.


Naming an Action

Each action in an application file must have a unique name. Tango Editor gives actions a unique name automatically.

The default name for an action is its action type. When you add an action that already exists in the application file with its default name, Tango appends the default name with a numeric starting at "1", for example, "Search1"


!Tip: To make your application files more readable, you should always replace default names with more meaningful ones.


To change the name of an action in an application file

You can also right click the name, and from the menu that appears, click Rename.

  1. Select the action you want to rename.
  2. Click the action's name, or from the Edit menu, choose Rename.
  3. Type the new name.

!Note: Action names can contain only letters, numbers, and underscores. No spaces, punctuation, or other characters are allowed. Adding spaces automatically adds underscores.


When you change the name of an action, Tango automatically updates any Branch actions in the same application file referring to the action. If you change the name of an action that is the destination for branches from other application files, the Branch actions in other application files are not updated.

Tango does not automatically update action results references for renamed actions.

Deleting an Action

To delete an action from an application file
  1. Select the action you want to delete.
  2. Do one of the following:
    • On the main toolbar, click the Delete icon.

    • From the Edit menu, choose Delete.
    • Press the Delete key.
  3. When the dialog box appears asking you to confirm the deletion, choose OK.

!Tip: You can bypass the confirmation dialog box by holding down the Ctrl key when choosing Delete.


Editing an Action

All of the actions--except Return, Group and Break actions--have associated attributes and parameters. You can set these parameters in the action's editing window.

To edit an action in an application file

Double click the action icon in the application file window.

The action's editing window opens.

If the action is associated with a data source, the Data Sources Workspace opens, listing the tables and columns for the data source. If Tango Editor has not loaded the data source yet, it is loaded first.

Moving an Action

Tango executes the actions in an application file sequentially, from top to bottom; however, you can use control actions to modify this sequence.

If you want the actions to be performed in a different order, you can rearrange them. Move them to another location in the application file by dragging them to the position you want.

To move an action to a new location

Do either of the following:

  • Select the action you want to move, and drag the action to its new position.
  • Select the action, and cut and paste it using the edit commands.

Actions are pasted after the currently selected action, or at the end of the file if no action is selected.

Edit commands are available from the Tango Editor Edit menu and from the context-sensitive menu.

When you move an action, Branch actions referring to it continue to branch to the action, even though its position has changed.

Copying an Action

You may want to create an action that performs a task similar to one performed by an existing action in another application file. Instead of having to recreate the action and specify all its parameters again, Tango Editor allows you to duplicate an action.

To copy an action in the same application file

Do either of the following:

  • Select the action you want to copy, and hold down the Ctrl key and drag the action to where you want the new action to appear.
  • Select the action, and copy and paste it using the edit commands.

Edit commands are available from the Tango Editor Edit menu and from the context-sensitive menu.

The copied action is given a new, unique name, which you should change to a more descriptive name.

To copy an action into another application file

Do either of the following:

  • Select the action you want to copy, and drag the action into another application file.
  • Select the action, and copy and paste it using the edit commands.

Edit commands are available from the Tango Editor Edit menu and from the context-sensitive menu.

Be careful when copying database actions. For an action to work correctly in the new application file, the data source must be the same as in the original one.

Alternatively, you may assign another data source to the action in the new application file.

Context-Sensitive Action Menu

When you right click an action icon in the application file window, or anywhere in the file window with an action selected, a context-sensitive menu of action commands appears.

  • Open opens the action editing window for the selected action.
  • Cut, Copy, Paste and Delete perform the standard window editing functions.
  • Rename allows you to edit the current name of the action.

For more information on using these commands, see:
"Assigning Attributes to Actions" , "Debugging Application Files" , "The SQL Query Window" , "Grouping Actions" , and "Action Properties"

  • Results HTML, No Results HTML, Error HTML, and Push are attributes you can assign to actions which support them.
  • Debug Application File is an attribute of the entire application file.
  • SQL Query opens the SQL Query window so you can perform SQL queries from within Tango.
  • Group and Ungroup allows you to group related actions and also to ungroup them.
  • Properties displays the action properties window.

Action Properties

When you select an action and choose Properties from either the Edit menu or the context-sensitive menu, the Action Properties window for that action appears.

This window displays current information about the selected action and the assigned data source.

For more information, see "Properties Window".

Using this window, you can change some of the action's properties.

[top] [back to top]


Assigning Attributes to Actions

In addition to the parameters specific to each action type, which are edited using the action's editing window, actions can also have the following attributes:

  • Results HTML applies to all actions, except control actions (other than Branch). After the action is executed, this HTML is added to the results returned.
  • No Results HTML applies only to Search, Direct DBMS, Script, File, and External actions. When the action does not return data, this HTML is returned instead of the Results HTML.
  • Error HTML applies to most action types except certain control actions (including Return and Break). In the event of an error in the action's execution, this HTML is returned immediately.
  • Push causes the Results HTML accumulated so far to be sent back to the Web browser when the action to which it is assigned finishes executing. Execution then continues normally.
  • Debug Application File lets you see useful information about your application file execution in your Web browser application. This attribute applies to the entire application file, not a particular action.






You can also right click the application file in Tango Editor and choose the attribute(s) that apply to that action from the context sensitive menu that appears.

To assign any of these attributes to an action (or, for Debug Application File, to the application file), select or open the action editing window, then select an attribute from the Attributes menu or from the Attributes bar.

Action attribute icons appear beside the action name in the Attributes column of the application file window to indicate which actions have any of these attributes associated with them.

For more information, see "HTML Editing Window".

You can switch between the Results HTML, No Results HTML and Error HTML associated with an action by clicking on the tabs at the bottom of the HTML editing window.

Results HTML

Many actions in an application file can have HTML associated with them. This HTML is stored in the Results HTML attribute. If Results HTML contains any text, the Results HTML icon appears in the attributes column of the application file window; otherwise, it does not.

As Tango Server executes the actions in a file, the Results HTML associated with each is accumulated. When execution of the file is complete, the HTML is returned.

Results HTML can also contain Tango meta tags that Tango Server processes. While all the other text in Results HTML is interpreted by the user's browser and returned as is (via the Web server), Tango Server first substitutes meta tags with other values.

For more information, see "Using Meta Tags".

The <@COLUMN> meta tag causes a database value to be placed in the HTML. There are many others, including tags for referencing form field and search argument values, and conditional tags for displaying HTML only if the result of a given comparison is true.

To edit the Results HTML for an action

You can also right click the action and choose Results HTML from the context-sensitive menu that appears.

  1. Select the action in the application file window.
  2. From the Attributes menu, select Results HTML, or click on the Attributes bar.

    The Results HTML editing window appears.

  3. Type the Results HTML into the HTML text area. The text can include any valid HTML2 or Tango meta tags.

    You can switch between the Results HTML, No Results HTML and Error HTML associated with an action by clicking on the tabs at the bottom of the HTML editing window.

For more information, see "Working With Snippets".

You can add column values (for Search actions only) and any HTML snippets you have defined to the Results HTML editing window from the Snippets Workspace. As well, you can add from the list of standard Tango snippets that allow for easy entry of many of the meta tags.

To include any of these items in your Results HTML, select the snippet and either drag it, or copy and paste it into the desired location in your text.

For HTML snippets that have placeholders for the current selection, select the text and drag the snippet over the selected text. The snippet is wrapped around the selection. For example, "Title" becomes "<H1>Title</H1>".

You can also easily add many of the common Tango meta tags.

  • Click the editing area where you want to add a meta tag.

For information on using the Insert Meta Tag dialog box, see "To insert common meta tags into your application file" .

  • Do either of the following:
    • From the Edit menu, choose Insert Meta Tag.
    • Right click, and from the context-sensitive menu that appears, choose Insert Meta Tag.

The Insert Meta Tag dialog box appears.

No Results HTML

You can associate No Results HTML text with Search, Direct DBMS, Script, and External actions. If the action execution does not return any data, this text is added to the application file's accumulated HTML instead of the Results HTML. This is useful when you want to display a special message to users when their queries do not return data.


!Note: If both Results HTML and No Results HTML appear as attributes, Tango accumulates one or the other, but never both.


After Tango Server processes the No Results HTML, execution of the application file continues normally to the next action.

No Results HTML can contain any of the Tango meta tags used in Results HTML, except for those related to displaying result data items, such as <@ROWS>, <@COLUMN>, and <@COL>.

Error HTML

Error HTML allows you to specify your own error messages in HTML format, instead of having Tango Server produce them. The other alternative is to modify the Error.htx file; see "To specify your own custom default error message" .

You can associate Error HTML with most actions. If an action fails for any reason, execution ends and the Error HTML for the action is returned immediately to the user.

Error HTML can contain all the Tango meta tags used in Results HTML, except for those related to displaying result data items.

For more information, see "<@ERROR>" and "<@ERRORS></@ERRORS>" in the Meta Tags and Configuration Variables manual.

There are also special Tango meta tags for displaying error information.

If no Error HTML has been assigned to an action and an error occurs in that action, Tango returns a default error message using the following HTML:

<h3>Error</h3>

An error occurred while processing your request:<p>
<@ERRORS>
Position: <b>
<@ERROR PART=POSITION></b><br>
Class: <b>
<@ERROR PART=CLASS></b><br>
Main Error Number: <b>
<@ERROR PART=NUMBER1></b><br>
<@ifequal
<@ERROR PART=NUMBER2> 0>
<@else>
Secondary Error Number: <b>
<@ERROR PART=NUMBER2>
</b><br>
</@ifequal><p>
<i>
<@ERROR PART=MESSAGE1><br>
<@ifequal
@ERROR PART=MESSAGE2> "">
<@else>
@ERROR PART=MESSAGE2><br>
</@ifequal><p>
</i>
</@ERRORS>

To specify your own custom default error message
  1. Create a text file containing the desired HTML and meta tags.
  2. Name the file error.htx.
  3. Place it in the C:\WinNT\Tango3\ directory under Windows NT, or in the C:\Windows\Tango3\ directory under Windows 95.

    If Tango Server finds this file, it processes and returns it instead of the built-in default Error HTML. Error HTML assigned to an action is used if it exists.

For more information, see "Configuring Tango Server" .

The name and location of this file is determined by the defaultErrorFile configuration variable, which can be modified using the config.taf application file. The values when Tango is first started are given above. If you modify the path or name of the error file, place the file in the directory you specified instead.

Push

The Push attribute causes the Results HTML accumulated so far to be sent back to the Web browser, when the action to which the Push attribute is assigned finishes executing. Execution then continues.

Normally, Tango waits until all execution is finished before returning the results at one time. If you want the user to see some of the results while Tango continues with the rest of the execution, set the Push attribute of the action.


!Note: Some browsers may not display table HTML immediately if you use the push attribute to return an unclosed table.


Debug Application File

For more information, see "Debugging Application Files"

[top] [back to top]


Adding HTML (Results Action)

The Results action adds HTML to an application file's results.

When you drag the Results action icon from the Actions bar into an application file, a blank HTML editing window appears.

Results HTML can contain special meta tags that Tango Server processes. While all the other text in Results HTML is returned as is to your Web browser (via the Web server), any meta tags are first substituted with other values by Tango Server. You can also associate Error HTML with the Results action.



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



1

Tango does not restrict its content to only HTML format. Using other markup languages such as SGML, VRML, and XML instead of HTML is also possible.

2

Tango does not restrict its content to only HTML format. Using other markup languages such as SGML, VRML, and XML instead of HTML is also possible. If you use other content types, you are responsible for setting the HTTP header appropriately.

docs@pervasive.com

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