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 Web 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, FileMaker Pro scripts, 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 palette
- working with actions
- assigning attributes to actions
- the Results action
- the Presentation action.
![[top]](arrow.gif){kind=icon}
[back to top] About Actions
The Actions palette shows all the available action types. It appears whenever an application file is active, or you choose Actions Palette from the Windows menu.
Tip: You can drag the Actions
palette to anywhere on your desktop.
You add all Tango actions to an application file from the Actions palette.
The following table lists each action, its function, and where in this User's Guide you can find more information:
As well as actions, the Actions palette 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 |
[back to top] Working With Actions
The application file window shows the actions that you want Tango Server to execute. Generally speaking, Tango Server executes actions sequentially, from top to bottom, until it encounters a control action. Control actions make decisions and cause execution to jump to another action or action group.
An action icon in the Action column indicates the type of action. Each action must have a name that is unique in the application file.
An action can have attributes. Action attribute icons in the Attributes column indicate which attributes are associated with the action on that row.
Some actions require database operations. The Object/Data Source column indicates which data source an action is associated with.
Adding an Action
To add an action to an application file
- Drag an action icon from the Actions palette into the application file window (the cursor changes to a closed hand and a box outline), 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 a closed hand), 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 option
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 action names with more
meaningful ones.
To rename an action in an application file
You can also control+click the name, and choose Rename from the contextual menu that appears.
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 rename an action, Tango automatically updates any Branch actions in the same application file referring to the action. If you rename 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
When the dialog box appears, asking you to confirm the deletion, click OK.
Tip: You can bypass the
confirmation dialog box by holding down the option key when
choosing Delete or Clear.
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
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
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
Select the action you want to copy, hold down the option key, and drag the action to where you want the new action to appear.
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
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.
Contextual Action Menu
When you control+click an action icon in the application file window, or anywhere in the file window with an action selected, a contextual menu of action commands appears:
For more information on using these commands, see "Setting Data Sources for Actions", "Assigning Attributes to Actions", "Debugging Files", "The SQL Query Window", "Grouping Actions", and "Action Properties".
Set Data Source allows you to set the data source for one or more actions.
Results HTML, No Results HTML, Error HTML, and Push are attributes you can assign to actions which support them.
Debug File is an attribute of the entire application file or Tango class 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.
Action Properties
When you select an action and choose Properties from either the Windows menu or the contextual menu, the Action Properties window for that action appears.
This window displays current information about the selected action and the assigned data source.
Using this window, you can change some of the action's properties.
Note: The Data Source and
Deployment Logon tabs are disabled when the action is not a database action.
[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 File lets you see useful information about your application file or Tango class file execution in your Web browser application. This attribute applies to the entire application file, not a particular action. For more information, see "Debugging Files".
To assign Results HTML, No Results HTML, Error HTML, or Push
Select the action in the application file window, then select an attribute from the Attributes menu or from the Attributes palette.
Control+click the action in the application file window and choose the attribute that applies to the selected action from the contextual menu that appears.
Action attribute icons appear beside the action name in the Attributes column of the application file window. See the example on An example of the application file 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 top 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 Web browser and returned as is (via the Web server), Tango Server first substitutes meta tags with other values.
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 create or edit the Results HTML for an action
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 top of the HTML editing window.
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.
To add a meta tag
The Insert Meta Tag dialog box appears. For information on using the Insert Meta Tag dialog box, see "Inserting Meta Tags" on page 137.
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>.
To create or edit the No Results HTML for an action
Select the appropriate action in the application file window (Search, Direct DBMS, Script, and External actions).
Type the No Results HTML into the HTML text area. The text can include any valid HTML or Tango meta tags.
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 see "To specify your own custom default error message"on this page.
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:
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
Create a text file containing the desired HTML and meta tags.
Save or copy it to the Tango 2000 folder under the Preferences folder within your System Folder.
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.
To create or edit the Error HTML for an action
Type the Error HTML into the HTML text area. The text can include any valid HTML or Tango meta tags.
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 Web browsers may
not display table HTML immediately if you use the Push attribute to return an
unclosed table.
Debug File
For more information, see "Debugging Files".
[back to top] Adding HTML (Results Action)
The Results action adds HTML to an application file's results.
Results HTML can contain Tango 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.
[back to top] Presentation Action
The Presentation action allows you to include individual presentation pages in your Tango application file. The file pointed to by the Presentation action--the presentation page--can contain HTML, Tango meta tags, or any other sort of document markup. When your Tango application file is executed on Tango Server, the presentation page is processed when that point in the application file is reached.
The Presentation action performs an operation similar to including an HTML or other file in a Tango application file with <@INCLUDE>. For more information, see "<@INCLUDE>" in the Meta Tags and Configuration Variables manual.
For more information, see "Working With Presentation Pages".
The file referenced by the Presentation action is part of the current project, and can be opened and edited by double-clicking on the file icon within the Presentation Pages folder in the Project section of the Workspace.
You can also designate files in your project as presentation pages, and manage files within the Presentation Pages folder.
Setting Up a Presentation Action
When you drag the Presentation action from the Actions bar into an application file, the Presentation dialog box appears.
In the Presentation Page field, enter the name of the presentation page, or if you have previously specified a presentation page in the current Project, choose a file name from the pop-up menu.
Click Choose to navigate to the location of the presentation page.
If the file is not in your current project, you are prompted to add it to the project, where it appears in the Presentation Pages folder and in the Files folder of the Project tab of the Workspace.
In the Path to page on server area, select Same as this file if the presentation page is located in the same folder as the current application file, or select Other.
If you choose Other, you specify the path to the presentation page. This value is a slash-separated path from the Web server document root, and may include literal text, meta tags, or both. To insert a meta tag in this field, control+click in the text field and choose Insert Meta Tag... from the contextual menu that appears.
For example, you could enter the following into the text field:
This example includes the specified file residing in the MyDirectory folder within the Tango2000 folder in the Web server document root folder.
This example includes the specified file residing in the same folder as the currently-executing application file.
Uses of the Presentation Action
The Presentation action can be used to separate the business logic of your Tango application from the presentation logic, so the two can be developed independently.
The Presentation action helps to allow development of Tango action and meta tag logic independently from the development of the HTML used to display the pages. The Presentation action points to this HTML page, so that developers working on Tango logic can work independently of those working on the actual pages presented to the user.
The Document Object Model (DOM) allows you to create your own complex data structures in XML, and return them into presentation pages. For more information about DOM, see "Document Object Model".