Meta Tags

<@VAR>

Syntax

<@VAR NAME=name[SCOPE=scope] [ELEMENT=Xpointer] [TYPE=text] [ENCODING=encoding] [FORMAT=format] [{array attributes}]>

Description

<@VAR> retrieves the contents of a variable, and, depending on the operation being performed, formats the data appropriately. Any of the attribute values of <@VAR> may be specified by other meta tags.

Text

When retrieving the contents of a text (standard variable), the result of <@VAR> is always a text string.

Arrays

<@VAR> may also be used to retrieve an array. However, <@VAR> does different things to arrays based on context: <@VAR> converts the array to text whenever the result of the tag is returned in Results HTML, or when TYPE=text is specified; <@VAR> returns an internal reference to the array when it is used to copy an array from one place to another. So, if <@VAR> is used within <@ASSIGN>, then no conversion to text is performed (unless the TYPE="text" attribute is specified).

There are array-returning attributes that can be used to specify prefixes and suffixes for the returned array, rows within the array, and columns within the rows. They are described in the section Array-to-Text Conversion Attributes. By default, the returned array is formatted as an HTML table.

DOM (XML document instance)

<@VAR> can be used to retrieve all or part of a document instance (XML) variable. The ELEMENT attribute can specify part of the document instance using Xpointer syntax. For more information on using Xpointer to return DOM variables, see Chapter 9 of the User's Guide.

A document instance is returned by <@VAR> as XML with no conversion of characters to HTML entities if the ENCODING attribute is not present. No conversion occurs even when XML is placed in HTML (for example, to be displayed as a Web page). All other ENCODING attribute settings function normally.

You can display encoded XML by first assigning the XML text to a variable (using the TYPE=TEXT attribute, which forces XML to be returned, not a document instance), and then returning the value of that variable in the HTML. The default encoding of variables returned with <@VAR> then takes place, for example:

<@ASSIGN tempXML <@VAR myDOM TYPE=TEXT>> <@VAR tempXML>

The XML is returned with the appropriate text converted to HTML entities.

Scoping Rules

Scoping is the method by which variables can be organized and disposed of in an orderly and convenient fashion. There are various levels of scoping, each of which has an appropriate purpose:

For more information, see Configuration Variables.

System Scope contains any variables that are general to all users. This scope contains only Tango Server configuration variables. To use this scope, specify SCOPE=system or SCOPE=sys.

For more information, see domainScopeKey and Chapter 8 and Chapter 24 of the User's Guide, or the Application Server Getting Started Guide.

Domain Scope contains variables that users can share if they are accessing a particular Tango application file from a specified Tango domain. Tango domains are specified in a domain configuration file, or default to the domain name (base URL or IP address) of the path to the Tango application file. This scope is defined by setting the system configuration variable domainScopeKey appropriately; that is, setting it to a value that can differentiate such users. By default, this is <@DOMAIN>, which returns the value of the current Tango domain.To use this scope, specify SCOPE=domain.

For more information, see Chapter 8 and Chapter 24 of the User's Guide or the Application Server Getting Started Guide.

Application Scope contains variables that are shared across Tango applications. Tango applications are defined by Tango users in an application configuration file. To use this scope, specify SCOPE=application or SCOPE=app.

For more information, see userKey, altuserKey and Chapter 8 of the User's Guide.

User Scope contains variables that a user defines and expects to be able to access from many application files or invocations of single application files. To use this scope, specify SCOPE=user or SCOPE=usr.
Local Scope contains variables that should be unique to every invocation of any application file. For example, this scope could be used for temporary variables that reformat output from a search action. All variables of this scope are removed when the application file concludes execution. To use this scope, specify SCOPE=local, or SCOPE=doc.
Instance Scope contains variables that are valid in an instance of a Tango class file. These variables can be shared across methods called on a Tango class file, if the methods are called on the same instance. To use this scope, specify SCOPE=instance.
Method Scope contains variables that should be unique to a method of a Tango class file. To use this scope, specify SCOPE=method.
Cookie Scope contains variables that are sent to the user's Web browser as cookies (that is, a small text file kept by the Web browser for a specified amount of time). To use this scope specify SCOPE=cookie.
Custom Scope is user-specified. It is outside of the scope search hierarchy.

Specifying Scopes

There are two methods of specifying a variable with a particular scope.

Use the SCOPE=scope attribute.
Leave out the SCOPE=scope attribute and specify a variable name as scope$myvariable; scope may be any valid scope specifier.

The behavior is undefined when both methods are used at once.

Scoping Precedence

When no scope is specified, Tango must find the variable by looking for the variable name within the various scopes. Tango has a set order in which it tries to find scopes. They are:

(in a Tango application file)
local--»user--»application--»domain--»system

(in a Tango class file)
method--»instance--»local--»user--»application--» domain--»system

Note: Variable scoping precedence for variables and configuration variables does not check cookie scope.

For more information, see domainScopeKey.

If domainScopeKey resolves to empty for the current user, then domain is not checked. If there is no current application, application scope is not checked.

Variable Shortcut Description

There is a shortcut syntax for returning variables as well, with or without scope: use a double @ and the name of the variable. The following two notations in each of the examples are equivalent:

<@VAR NAME="homer"> @@homer

<@VAR NAME="homer" SCOPE="domain"> @@domain$homer

Configuration Variables

For a detailed list of configuration variables, see Chapter 2 of this manual.

Tango reserves special variables that contribute to the configuration of the server and also that provide default behaviors for users.

For more information, see "About Variables" in Chapter 8 of the User's Guide. For more information on setting configuration variables using the config.taf file, see the Application Server Getting Started Guide or Chapter 24 of the User's Guide.

Configuration variables that control basic configuration of the server only exist in the system scope. Some configuration variables are valid in all scopes, or some scopes (for example, certain configuration variables are valid only in application and system scope); if so, they are subject to the full scoping mechanism described previously. Default values read from the preference file are stored in the system scope.

Examples

Accessing a local variable:

<@VAR NAME="foo" SCOPE="local"> <@VAR NAME="local$foo"> @@local$foo

Accessing a user variable:

<@VAR NAME="foo" SCOPE="user"> <@VAR NAME="user$foo"> @@user$foo <@VAR NAME="foo" SCOPE="usr"> <@VAR NAME="usr$foo"> @@usr$foo

Accessing a system scope variable:

<@VAR NAME="foo" SCOPE="system"> <@VAR NAME="system$foo"> @@system$foo <@VAR NAME="foo" SCOPE="sys"> <@VAR NAME="sys$foo"> @@sys$foo

Accessing a domain scope variable:

<@VAR NAME="foo" SCOPE="domain"> <@VAR NAME="domain$foo"> @@domain$foo

Accessing variable using scoping precedence:

<@VAR NAME="foo" > @@foo

Getting an array and formatting it for Results HTML:

<@VAR NAME="array">

Getting part of an array and formatting it for Results HTML:

<@VAR NAME="array[3,*]">

Getting an array and formatting it for Results HTML with attributes:

<@VAR NAME="array" APREFIX='<TABLE BORDER="2">' ASUFFIX= </TABLE>' RPREFIX='<TR>' RSUFFIX='</TR>' CPREFIX='<TD BORDER="2">' CSUFFIX='</TD>'>

Copying an array without formatting it (converting it to text):

<@ASSIGN NAME="array2" VALUE="<@VAR NAME='array'>">

Copying part of an array without formatting it:

<@ASSIGN NAME="array2" VALUE="<@VAR NAME='array[*,4]'>">

Copying the formatted representation of an array to a variable:

<@ASSIGN NAME="array2" VALUE="<@VAR NAME='array' FORMAT=text>">

Getting a document instance variable (XML) and performing no encoding on it:

<@VAR NAME="myDom">

Getting part of a document instance variable:

<@VAR NAME="myDom" ELEMENT="root().child(2)">

Copying a document instance:

<@ASSIGN NAME="myDom2" VALUE="<@VAR NAME='myDom'>">

Copying part of a document instance:

<@ASSIGN NAME="myDom2" VALUE="<@VAR NAME='myDom' ELEMENT='root().child(2)'>">