Extending Tango Functionality
Script and External Actions
The Script action provides an interface within Tango for executing JavaScript code at the server. The script executed can return to Tango a value you can access using Results HTML.
The External action sends a specified Apple Event with parameters to a specified application and retrieves the results or invokes a Java class file and returns results. On Windows and Unix platforms, the External action calls an executable invoked using a command line, a Dynamic Link Library (DLL), or Java class file, and, if desired, returns results.
Tango may also be extended through JavaBean and Tango class file objects. For more information, see "Tango and Objects".
This chapter covers the following topics:
- setting up and executing a Script action
- configuring a DLL call or a Java action
- using a command line
- assigning variables to action parameters
- assigning action attributes
- deleting action parameters
- executing an External action.
![[top]](arrow.gif){kind=icon}
[back to top] Executing JavaScript
The Script action provides an interface for executing core JavaScript code at the server. The script executed can return a value to Tango, which is accessible using Results HTML.
Tango is JavaScript 1.4 compatible, meaning it includes the official JavaScript Reference implementation from Netscape, and conforms to version 1.4 of the language.
Note: Tango supports the
general purpose core of the language. The objects representing the Web browser
and its contents are not supported, because the scripts are executed
at the server where these objects do not exist. For your convenience, a
JavaScript HTML reference is provided with the Tango HTML help.
Setting Up a Script Action
When you drag the Script action icon from the Actions palette into an application file, the Script action editing window appears.
The JavaScript object and variable scope parameter defines the lifetime of the objects and functions declared in the script. This is a concept similar to the scope of variables in Tango.
The pop-up menu/text box has several choices, or you can enter a custom scope:
Default specifies Tango's default scope, which is set by the defaultScope configuration variable. For more information, see "How Tango Determines Default Scope in Variable Assignments".
Immediate specifies that the objects and functions go away immediately after the action is executed.
Method specifies that anything defined in the script can be referenced within the current method of a Tango class file.
Instance specifies that anything defined in the script can be referenced within the current instance of a Tango class file.
Note: Method and Instance
appear only if the Script action is within a Tango class file.
Local specifies that anything defined in the script can be referenced in another script in the same application file execution.
User specifies that anything defined in the script can be referenced in another script run by the same user.
Application specifies that anything defined in the script can be referenced in another script in an application file in the current Tango application.
Domain specifies that anything defined in the script can be referenced in another script in an application file in the Tango domain.
For information on using the script text area, see "HTML Editing Window", and "The SQL Query Window".
You enter the text script to be executed in the JavaScript script text area. The script may contain meta tags. All meta tags in the script are substituted before the script is executed.
Tip: You could use an
<@INCLUDE> meta tag to reference an external JavaScript file.
For more information, see "<@INCLUDE>" in the
Meta Tags and Configuration
Variables manual.
The script text area functions the same as HTML text editing windows.
Executing a Script Action
Tango Server executes the Script action in a similar way it executes the <@SCRIPT> meta tag.
For more information, see "<@SCRIPT>" in the Meta Tags and Configuration Variables manual.
Any value returned by a script is accessible in the Results HTML by using <@COL 1> inside a <@ROWS> block. The action's result set (a 1 by 1 array) is also stored automatically in a local variable, resultSet.
[back to top] Using an External Action
Setting Up an External Action
When you drag the External action icon from the Actions palette into a file, the External action editing window automatically opens.
The default External action type is based on the current platform, in this case, Apple Event. You can also specify Java, command line execution, or DLL.
From the Type pop-up menu, select the type of action you want to execute.
Note: If you specify
parameters for one type and then change to another type, Tango attempts to
transfer the current parameters to the new type.
This User's Guide gives a description of each type of External action. Only an Apple Event or Java action can be used with the Mac OS version of Tango Server. The DLL and Command Line externals are available if you plan to deploy your application file on another Tango Server platform, such as Windows or UNIX.
Configuring an Apple Event
To use External actions, you should be familiar with Apple Events and know the event and parameter codes of applications with which you want to communicate. You can also use Apple Event actions to communicate with applications you write in AppleScript.
To configure an Apple Event external action
From the Type pop-up menu, select Apple Event.
The External action editing window for the Apple Event type appears.
The Apple Event dialog box has several components. Enter the required information, as follows:
Target Application. The path to the application to send the Apple Event to. The path must be colon (:) or slash (/) separated, for example,
The server administrator may specify a path which limits External actions. For more information, see "absolutePathPrefix" in the Meta Tags and Configuration Variables manual.
Event Class Code. The case-sensitive, four-letter class code of the event to send to the target application.
Event Code. The case-sensitive, four-letter code of the event to send to the target application.
Event Parameters. Parameter keyword codes are all case-sensitive, four-letter values defined by the target application. To specify the direct parameter for an event, use four dashes, "----".
A blank row appears in the Parameters area.
The parameter values can be entered as fixed values, or you can use any Tango meta tags that return values.
Calling AppleScript Applications
Tango can send only text parameters and accepts only a string (or value that can be converted to a string), list of strings, or list of lists of strings as return values.
If you need to communicate with applications requiring non-string parameters or that return results in a format Tango cannot handle, you should use an intermediate AppleScript application to coerce the non-string types to strings.
For more information on Apple Events and AppleScripts, consult your Macintosh documentation.
AppleScript application handlers that are to be called from Tango require special subroutine names and parameter labels. Here is an example:
on «event TNGOTest» dir_param given
«class arg1»:arg_1, «class arg2»:arg_2
set col_one to¬
"Here is argument 1, accessible with a <@COL 1> tag: " &
arg_1
set col_two to¬
"Here is argument 2, accessible with a <@COL 2> tag: " &
arg_2
set col_three to¬
with a <@COL 3> tag: "¬& dir_param
return {col_one, col_two, col_three}
The chevrons (« and ») in the handler name and argument specifications are entered using option-\ and option-shift-\ key combinations.
The first four letters of the AppleScript handler name (after the event keyword) make up the Event Class Code; the second four are the Event Code. In this example, the event class is TNGO and the event is Test.
Except for the direct parameter, which immediately follows the handler name, the parameters must be labeled with the class keyword and a unique four letter code. In this example there are three parameters: the direct parameter, "arg1", and "arg2".
As with any other applications Tango communicates with through Apple Events, results from an AppleScript application must be returned as a string, list of strings, or list of lists of strings. Here is an example of each:
Configuring a DLL Call
To configure a DLL call
From the Type pop-up menu, select DLL.
The External action editing window for the DLL type appears.
In the DLL field, type the fully qualified path to the DLL you want to call, for example:
C:\Program Files\Tango2000\externals\Test.dll.
Note: The path specified here
is appended to the value of the absolutePathPrefix configuration
variable. If this configuration variable has a value (in either application or
system scope), this field should contain a path relative to that
location. For more information, see "absolutePathPrefix" in the
Meta Tags and Configuration
Variables manual.
Insert a new parameter row by doing one of the following:
A new parameter row appears. The parameters are numbered for easy identification.
Tip: You may re-order
parameters by dragging them within the list.
In the Value field, type a parameter value.
All parameters are passed to the corresponding APIs by pointers of type (char *). Parameter values may include any value-returning Tango meta tags, which are substituted when the action is executed.
Using a Command Line
External actions allow you to run any executable file (for example, batch file, shell or Perl script, C application) and, if desired, retrieve results. Values are passed from Tango to the executable by means of environment variables. Results are retrieved by Tango from text that the external action has written to the standard output stream (stdout). Rows and columns are delimited with tabs and returns, respectively.
To configure a command line External action
From the Type pop-up menu, select Command Line.
The External action editing window for the Command Line type appears.
In the Command field, specify the executable file name.
The value of this field (after meta tag substitutions) must be a valid file path (for example, c:\temp\dir.bat). Command line parameters are not allowed here.
Note: The path specified in
the Path field is appended to the value of the
absolutePathPrefix configuration variable. If this configuration
variable has a value (in either application or system scope), this field should
contain a path relative to that location. For more information, see
"absolutePathPrefix" in the
Meta Tags and Configuration
Variables manual.
You may include command line switches here (Unix only).
Note: A command line
containing a DOS-like command (for example, dir) does not work because
`dir' is not a file. Commands calling other command processors (shell) also do
not work. If you want to execute an operating system command, you should create
a batch file or shell script.
On Unix, shell scripts must have read/execute permission for the user running the Tango daemon. In order to be properly executed under the appropriate shell, the shell script must have a shell execution directive such as #!/bin/sh as its first line.
Insert a new environment variable row by doing one of the following:
In the Name field, enter the name of an environment variable to create for the process. This value is passed on the command line to the External action.
Note: The name of an
environment variable is case sensitive.
In the Value field, enter the value to assign to the named environment variable.
Environment variables may include any value-returning Tango meta tags, which are substituted when the action is executed.
Tip: You may re-order variable
rows by dragging them within the list.
Configuring a Java Action
Tango ships with its own Java server. The Java server is on the same machine as Tango Server. The Java type external action allows you to connect to the Java server.
To configure a Java external action
From the Type pop-up menu, choose Java.
The External action editing window for the Java type appears.
In the Java Server field, type the IP address or hostname.domain of the machine running the Java server.
The default server name is localhost (127.0.0.1), meaning that the Java server is on the same computer as Tango.
In the Port field, type the port number the Java server is listening on. The default port is 4000.
Select either Java Class or Java Bean to specify the type of Java file.
In the Path field, type the fully qualified path to the Java file. This path can contain meta tags.
Note: The path specified here
is appended to the value of the absolutePathPrefix configuration
variable. If this configuration variable has a value (in either application or
system scope), this field should contain a path relative to that
location. For more information, see "absolutePathPrefix" of the Meta
Tags and Configuration Variables manual.
When specifying the path to your class file in the Java action, you must use the Java dot notation, starting at the location of the JAS. For example, if the class file is in a folder called java, inside the folder that the JAS is in, the path would be java.Hello.
Insert a new argument row by doing one of the following:
A new argument row appears. The arguments are numbered for easy identification.
Tip: You may re-order
arguments by dragging them within the list.
Appendix B provides additional information on calling Java classes from Tango.
Arguments may include any value-returning Tango meta tags, which are substituted when the action is executed.
Assigning Attributes
You can also assign the following attributes to an External action:
For a description of each attribute, see "Assigning Attributes to Actions".
You assign these attributes using the Attributes menu.
You can also control+click the External action icon or name in the application file, or click the open External action editing window to display a contextual menu of available attributes. The Properties command is also available in this menu.
If you control+click an action parameter, the Edit command is active allowing you to edit the parameter value; otherwise, it is disabled (grayed).
Deleting Parameters
To delete an External action parameter
Select the parameter row you want to delete, and do one of the following:
When you are asked to confirm deletion of the selected row, click OK.
Executing an External Action
When an External action is executed, the DLL, command line, or Java specified is called and the parameters are passed to it. An Apple Event, along with any parameters specified, is sent to the target application.
For more information, see "<@COLUMN>" in the Meta Tags and Configuration Variables manual.
Any results returned are accessible in Results HTML in the same way as in the Search action--by using a <@ROWS></@ROWS> block. The <@COLUMN> meta tag, however, does not work in the External action. You must use the <@COL> meta tag along with an item number to refer to data items, as the items do not have names.
A single item result is treated as a one-column row, a list of items is treated as a row of columns, and a list of lists is treated as a rowset.
For example, if an External action returns a list of lists of three data items each, all the results can be viewed with the following Results HTML:
For more information, see "<@ROWS> </@ROWS>" in the Meta Tags and Configuration Variables manual.
<@ROWS>
Row <@CURROW>, Item 1: <@COL 1><BR>
Row <@CURROW>, Item 2: <@COL 2><BR>
Row <@CURROW>, Item 3: <@COL 3><BR>
<HR>
</@ROWS>
For the command line and Java options, the value returned is treated as tab and return delimited: a tab separates columns and a return separates rows. (For DLLs, rows and columns are determined by the Tango DLL interface: see the Tango 2000 User's Guide for Windows for details.)
Only textual data can be returned from an External action. If any data item retrieved from an Apple Event is not a text string, Tango tries to convert it to a text representation. Most standard Apple Event data types can be converted to text; one exception is Boolean data items. If Tango cannot convert the data to a string, an error occurs.
The entire result rowset from an External action is automatically assigned to a local array variable, resultSet.
If the External action generates no data, and you have specified No Results HTML for the action, that HTML is processed instead of the Results HTML.
[back to top] Disabling JavaScript, Java and External Actions
You can specify that external actions only are executed in a specified directory of Tango Server using the absolutePathPrefix configuration variable. Using this configuration variable to set the path ensures that users cannot access directories other than the specified ones when using the External action.
JavaScript, Java, and External actions are by default enabled in Tango. If you want to disable (or enable) these features, you can do so by changing the following options in the Configuration Manager (the config.taf application file), in the Feature Switches screen: