Using Control Actions

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

	Chapter Fourteen Using Control Actions Setup and Operation of Branch, If, Loop, Break, and Return Actions Tango application files can contain control actions that control the execution of other actions in the file. This chapter covers the setup and operation of the following actions. The Branch action causes a jump to a designated action or group. The If action evaluates an expression and based on the result of that expression affects the control flow of the file. The Loop action repeats a set of contained actions a given number of times or while an expression evaluates to true. The Break action terminates processing in the loop. The Return action ends execution of the application file and returns any accumulated Results HTML to the Web browser. It can also return to another application file. [back to top] Jumping to a Designated Action (Branch Action) The Branch action causes a jump to a designated action or to an action group. You can set the Branch action to jump to a different action in the same file the Branch action is in or an action in another file. There are restrictions on what position and kinds of action a Branch action can jump to. Branch Action Destination Rules Branch actions have the following rules for valid destinations: Branch actions can only branch to an action at the outermost level in a different file. Branch actions are allowed to branch to any action at the same level in the same block of Tango actions. Branch actions are allowed to branch to any action at the outermost level. Branch actions are allowed to branch to any action that is an immediate parent. Branch actions are allowed to branch to an action that is a first-level child of an immediate parent. Branch actions cannot branch to Else If or Else actions. The preceding rules mean that Branch actions cannot branch to an action that they dominate or that a sister action dominates. For example, look at this application file:
	Examples of valid branches are: Action2 can branch to Action5. The actions are in the same action block and at the same level. Action2 can branch to Action7. Action7 is at the outermost level. Action3 can branch to If_2 and If_1. Those actions are immediate parents of Action3. Action3 can branch to Action2. Action2 is the first-level child of an immediate parent of Action3, If_1. Examples of invalid branches are: Action1 cannot branch to Action4. They are not in the correct relationship: Action4 is downward from Action1. Action2 cannot branch to Action6. They are not in the correct relationship: Action6 is downward from Action2. Action2 cannot branch to ElseIf3. Even though ElseIf3 is the first child of a immediately dominating parent action (If_1), this branch is not allowed because branching to an Else If action is invalid. Branching to Other Application Files When Caching is On If a Branch action is used to branch to another application file when document caching is on (as it is by default), changes to the branched-to application file are ignored; that is, the cached version of the file is executed when the Branch action executes, rather than the new one. This may affect ease of development of the application files involved; it may be helpful to do one of the following: Disable document caching while developing application files that branch to other files. Open the configuration application file with your browser, click Memory, and disable the Cache Files option. If you modify a branched-to application file, also make a change to the document containing the Branch action and save it. Both application files will be reloaded in this case. Setting Up a Branch Action
	When you drag the Branch action icon from the Actions bar into an application file, the Branch action editing window appears. To set up a Branch action From the Application File drop-down list, select the file you want the Branch action to jump to. If the selection is Current, you select the target action from the application file you added the Branch action to. If the current file is part of a project, the list also shows the other files in the project. If you want to select an application file from your hard drive, choose Others from the drop-down list. A standard file selection dialog box appears to select an application file with. If you select an application file that is not the current file, the Action list changes to show the actions in the selected file. The File path on server section is also enabled to allow you to specify the path to the application file. Do either of the following: Select the Same as this file's option (the default) to cause Tango Server to always look in the current file's folder. Specify in the Other field the path to the desired folder, which causes Tango Server to look for the application file in that location. This path is specified relative to the Web Server's document root directory. Enable the Return to next action after branch option if you want execution to continue with the action following the Branch action when a Return action is encountered in the destination. Disable this option if you want execution to end when a Return action is encountered in the destination. In the Action list, select the action you want the branch action to jump to. The destination action for a Branch must be valid according to the rules in "Branch Action Destination Rules" ; otherwise, an error is returned. Executing a Branch Action When Tango Server executes a Branch action, it jumps to the designated action. If the Return to next action after branch option is selected, Tango returns to the action following the Branch action when a Return action is encountered. [back to top] Conditional Action Execution (If Action) The If action evaluates an expression and based on the result of that expression affects the control flow of the file. The If action also has two related actions called Else If and Else. The If action can exist with or without one or more Else If actions and with or without a single Else action. The general forms of these actions are as follows: If Action If action (expression) group of actions to execute if expression evaluates to true remainder of actions in file If and Else Actions If action (expression) group of actions to execute if expression evaluates to true Else action only evaluated if If action evaluates to false group of actions to execute if expression evaluates to false remainder of actions in file If, Else If, and Else Actions If action (expression) group of actions to execute if expression evaluates to true Else If action (expression) only evaluated if If action evaluates to false group of actions to execute if Else If expression evaluates to true Else action group of actions to execute if none of the If or Else If expressions evaluate to true remainder of actions in file
	Setting Up an If Action
	When you drag the If or Else If action icon from the Actions bar into an application file, the If action editing window appears. By default, the If action editing window appears in its basic view, allowing you to create expressions quickly. An expression line appears in the dialog box, ready for you to edit. Note: Dragging the Else action icon into an application file does not open any action editing window. However, if you double click an Else action in an application file, the action editing window opens so you can change the Else action to an If or Else If action.
For more information, see "Advanced View".	An advanced view is also available that gives you more flexibility than the basic view when specifying evaluation expressions. You change the type of If action by selecting If, Else If, or Else from the Action drop-down list. The If and Else If action editing windows are basically the same, and you enter evaluation expressions the same way for both of them. When you select Else, however, only the Action drop-down list is active. This allows you to change to another If action type. Note: If you change back to an If or Else If action type from an Else action type before closing the action editing window, any If or Else If expressions you specified previously are retained. Basic View To specify values for the basic view parameters
For more information, see "Logical Operator". For more information, see "Operator".	Specify values as follows: Logical Operator. The first field in the expression list is the logical operator. There are two logical operators: and and or. Click the row, then click the field to display a drop-down list to choose an operator from. The logical operator is used when the expression includes more than one row. Value. Enter the values to use in the expression. The values can contain any value-returning Tango meta tags, which are substituted when Tango Server executes the action. Oper. Specify the operator to use to compare the two values specified.
For more information about inserting meta tags in entry fields, see "Inserting Meta Tags".	You can also use the Insert Meta Tag command to enter many of the commonly used meta tags. To insert a meta tag, either click the field and choose Insert Meta Tag from the Edit menu, or right click the field and choose Insert Meta Tagz` from the context-sensitive menu that appears. To add a new parameter row Do one of the following: From the Edit menu, choose Insert. On the main toolbar, click the Insert icon. Right click the list area, and choose Insert from the context-sensitive menu that appears.
	A blank row appears. Advanced View When you click Advanced in the basic view, the following happens: The window expands to show a text area where you can enter text-based expressions. The expression list in the basic view is disabled (appears grayed). The Advanced button changes to Basic. Any expression in the basic list is automatically converted to a text expression in the advanced text area. The advanced view presents a free-form text area to give you more flexibility than the basic view when specifying evaluation expressions. For example, if you want to use parentheses to control the evaluation order, you can enter the expression in this area.
For more information, see "<@CALC>" in the Meta Tags and Configuration Variables manual.	The expression entered here takes the same form as expressions specified for the `<@CALC>` meta tag. If the expression evaluates to "1" or "true", the expression is considered to be true; otherwise, it is considered to be false. You can automatically regenerate an expression appearing in the basic view in the advanced view as follows: In the advanced text area, right click where you want the expression to appear, or select the text you want to replace and right click. From the context-sensitive menu that appears, choose Insert Expression As Above. The expression appears in text form in the advanced text area. Tip: You can also drag text from the Snippets Workspace to this text area. To return to the basic view, click Basic. Caution: If you changed the expression in the advanced view, your changes are lost when you return to the basic view. An alert box asks if you want to continue. Performing Operations on If Actions Working with If actions is similar to working with grouped actions. For information on the operations you can perform on groups, see "Working With Action Groups" . Executing an If Action If Tango Server evaluates the expression to true, action processing continues with the list of indented actions. If the expression evaluates to false, action processing jumps to the first action after the list of indented actions, which could be an Else or Else If action. If that action is an Else If action, Tango Server evaluates the Else If expression to determine whether it should execute the indented actions under the Else If action. If the action is an Else action, then Tango Server executes the actions indented under the Else action. Once processing of the indented actions is complete, processing continues with the next non Else If or Else action at the same level as the If action. Tip: If actions may be nested; that is, the actions nested under an If action may contain other If actions. [back to top] Repeating Actions (Loop Actions) Loop actions repeat the execution of a set of contained actions for a given number of times or while an expression evaluates to true. Tip: The action list can contain nested Loop actions, that is, loops within loops.
For more information, see "Exiting a Loop (Break Action)".	Tango also includes a Break action you can use to exit a Loop action before the loop conditions for termination are met.
For more information, see "For Loop".	There are two kinds of Loop actions: While Loops and For Loops. Setting Up Loop Actions While Loop
	A While Loop action executes the actions in the loop while an expression evaluates to true. When you drag the While Loop action icon from the Actions bar into an application file, the While Loop action editing window appears in its basic view, allowing you to create evaluation expressions quickly. If the expression you specify does not evaluate to true when Tango first executes the While Loop action, the enclosed actions are never executed. Caution: Make sure that at least one value being compared in the expression is being changed inside the loop. If this is not the case, a "true" evaluation causes Tango to execute the enclosed actions forever. Be careful when constructing a While Loop expression. You want to ensure that it eventually evaluates to false.
For more information, see "Basic View".	The basic view for a While Loop action is similar to the basic view for If and Else If actions.
	The While Loop action editing window also has an advanced view that gives you more flexibility than the basic view when constructing evaluation expressions. For example, you can use parentheses to control the evaluation order.
For more information, see "Advanced View".	This view is similar to the advanced view for If and Else If actions. For Loop The other loop action is the For Loop action, which repeats a set of contained actions for a given number of times. When you drag the For Loop action icon from the Actions bar into an application file, the For Loop action editing window appears
	. Set the parameters in a For Loop action as follows: Counter Variable (local). The name of a local variable to use to access the current value of the counter. Note: This parameter is optional. It is not required to use the action. Start Value. The starting value for the loop counter. The default is 1. Count. The direction of the counting from the starting value to the ending value. You must specify this parameter so Tango can increment or decrement the counter properly. Choose Up or Down from the drop-down list to set the counter to increment or decrement, respectively. The default is Up. When Down is selected, the Increment By field name becomes Decrement By. To. The ending value for the loop counter. Increment/Decrement By. The value the counter increments or decrements by on each loop. Tip: All For Loop action fields, except for the Count field, support Tango meta tags. Performing Operations on Loop Actions Working with Loop actions is similar to working with grouped actions. For information on the operations you can perform on grouped actions, see "Working With Action Groups" . Executing Loop Actions While Loop Tango Server evaluates the expression before executing the contained actions. If the expression evaluates to true then the contained actions are executed. Then, Tango returns to the While Loop action and re-evaluates the expression. If it is true, the contained actions are executed again. This process continues until the expression evaluates to false. Execution then continues at the next action outside the loop. If Tango Server finds the expression is invalid, it returns a runtime error. Tango Server evaluates any meta tags in the expression on each pass through the loop. For Loop If Start Value is a meta tag, Tango Server evaluates it prior to the first pass through the loop. If the To and Increment/Decrement By fields contain meta tags, Tango Server evaluates them on each pass through the loop. At the end of the loop, execution returns to the top. This process continues until the loop counter exceeds the value specified in the To field. Execution then continues with the next action outside the loop. [back to top] Exiting a Loop (Break Action) The Break action prematurely terminates processing in a loop or group action. On termination, processing continues at the next action after the loop or group.
	Drag the Break action icon from the Actions bar into a Loop or Group action at the point you want the loop or group to terminate. On execution, the Break action terminates the loop, and processing continues at the next action after the loop. Note: If you include a Break action outside a loop or group, on execution Tango Server generates a runtime error. [back to top] Ending File Processing (Return Action)
	The Return action ends application file processing and returns any accumulated Results HTML to the Web browser.
For more information, see "Jumping to a Designated Action (Branch Action)".	The exception to this is if the current execution flow is the result of a Branch that had its Return to next action after branch option set. In this case, the execution returns to the action following the Branch when a Return action is encountered.