Meta Tags

For information on objects, see Chapter 21 and Chapter 22 of the User's Guide. For information on Tango class files, see Chapter 23 of the User's Guide.

Tango allows the use of custom meta tags, which are user-defined Tango meta tags that map directly to any method call supported by Tango, and can be used to call Tango class files, COM objects, and JavaBeans from Tango application files and Tango class files.

Custom meta tags can apply to all of Tango Server (system scope) or be specific to an application (application scope). Custom meta tags can be shared with other developers by distributing the tag definition file and any objects called by the custom meta tag.

The following sections describe using custom meta tags, creating a file that defines one or several custom meta tags, and the process of installing custom meta tags.

Using Custom Meta Tags

Once a custom meta tag has been created and installed on your system, all a user needs to do is type in the custom meta tag with any required attributes in any place where meta tags can be specified. The object instance is created, and a method call to the specified object is made when Tango Server executes the file. There are some issues to be aware of when using custom meta tags, described in this section.

Attributes of Custom Meta Tags

Required attributes of a custom meta tag must be specified when that custom meta tag is used; otherwise, Tango generates an error (naming the first missing attribute), and execution ends.

All custom tags have two standard attributes: FORMAT, and ENCODING. Returned values are encoded according to the ENCODING attribute, and formatting according to the FORMAT attribute, if either or both of these attributes is specified when the custom meta tag is used in an application file or class file.

Tag Name Conflicts

Application-specific custom meta tags can share names with system scope custom meta tags, in which case the application scope tag is used. Within a particular scope--application or system--tag names must be unique; Tango generates a warning in the event log and uses the first tag when a duplicate name is encountered within a scope.

Caution: If a custom meta tag has the same name as a built-in Tango meta tag, the custom meta tag does not work; the Tango meta tag takes precedence.

Custom Meta Tag Limitations

All custom meta tags are "empty" tags; that is, custom meta tags can have attributes but not content, because they do not have start and end tags.

Tags can only call objects that are defined within the current tag definition file.

Creating Custom Meta Tags: Tag Definition File

You define custom meta tags in tag definition files, which are XML files. These files must reside in a specific directory for system scope custom meta tags, and specific directories for application-specific custom meta tags (different directories for each application).

The customTagsPath configuration variable, available in system and application scope, defines the path to the directories where tag definition files reside.

A tag definition specifies a custom tag and the object and method to call for the custom tag. A custom tag definition file contains one or more tag packages, which each contain at least one object specification and at least one tag definition. A tag package groups related tags and shares objects with other tag packages.

You define custom meta tags by creating tag definition files based on a specific XML document type definition (DTD) developed by Pervasive Software.

Custom Tag Definition File Format

The format of the XML custom meta tag definition file is given by ctags.dtd, which resides in the XML directory under your Tango2000 directory.

Note: XML is case-sensitive. The names of the XML elements in tag definition files must be capitalized exactly as shown (for example, <packages>).

The following is an annotated custom meta tag definition XML file, describing each element:

<tagpackages> root element <packagedef ID=required; defines package with unique identifier> <author>optional; author of package</author> <version>optional; version of package</version> <copyright>optional; package copyright info</copyright> <packagedesc> optional; description of package </packagedesc> <objects> specifies settings for the used/created object <objectdef ID=required; a name you choose to uniquely identify the object used in the tag definition. type=required; type of object (COM, JavaBean, or TCF)systemobject=optional; default is false; if true, Tango uses an existing instance instead of creating a new one (COM objects only).<name>required; ProgID or ClassID (for COM); Tango class file name; or JavaBean name. This is the same name that must be specified in the <@CREATEOBJECT> meta tag. For COM and JavaBean methods, the method name is case-sensitive. For more information, see <@CREATEOBJECT>.</name> <varname>optional; when specified, Tango uses this object instance variable. If you want the tag processing to create the object instance named here, you must specify the scope and name elements and the TYPE and ID attribute of <objectdef>. If you want to be responsible for creating the instance before calling the custom tag, you need only specify the <scope> element. If the named object instance variable does not exist, it is created. If <varname> is not specified, a temporary variable is used to create the instance of the object called by the custom meta tag; this instance goes away immediately after processing of this tag has finished.<varname> may contain Tango meta tags.</varname> <initstring>optional; used to create monikers for COM objects
</initstring> <scope>scope in which object instance is created or obtained from (application, domain, user & local are allowed). May contain Tango meta tags.
</scope> </objectdef> <tags>list of tags in the package<tagdef name=tag name; must begin with a letter and may contain letters, numbers or underscores; no `@' is required.
objectid=identifies object (ID of an OBJECT element in the same package) whose method is called by this tag. methodtype=(JavaBeans and COM only): INVOKE (default), SET or GET; see <@CALLMETHOD> for more details. <method>name of method to call </method> <encoding>optional; determines the encoding used for the return value of the tag; if NONE is specified, value is not encoded, even if the tag is used in Results HTML. If element is not specified, Tango encodes the return value as it does other tags, determined by context; special characters are encoded if in Results HTML. Can be overridden by the ENCODING attribute of the custom meta tag. For more information, see Encoding Attribute. </encoding> <tagdesc>optional; describes tag for editing environments</tagdesc>zero or more attributes <attrdef> per tag
<attrdef name=name of custom tag attributerequired=optional; TRUE or FALSE (default) determines whether this attribute may be omitted when tag is used> <defaultvalue>sets an optional default value for the attribute; ignored if required set to TRUE </defaultvalue> <attrdefdesc>optional description of the attribute</attrdefdesc> </attrdef> </tagdef> </tags> </packagedef> </tagpackages>

All leading and trailing whitespace between and within start and end tags in the custom tag definition files is ignored.

Note: Tango meta tags are supported only in the above-noted elements of tag definition files; elsewhere, they cannot be used.

Loading Tags

Tango Server loads tag definition files from the directories defined by the customTagsPath configuration variable. All files in the directory specified by customTagsPath, and any subdirectories, are loaded.

Tag definition files for system scope load before the URL defined by the startupURL configuration variable; this means that custom meta tags are available for use in the application file called by the startupURL configuration variable.

Reloading Custom Meta Tags

The <@RELOADCUSTOMTAGS> meta tag forces a reload of the specified scope's custom tags file. The default value of the scope attribute is system. This tag requires that the user scope configPasswd match the configPasswd configuration variable for the scope requested (system or application).

Returning Information on Custom Meta Tags

The <@CUSTOMTAGS> meta tag returns an array of all custom meta tags in the specified scope. The names of the array's columns (name, package, and scope) are put into row 0 of the array. No password is required to use this tag.

Installing Custom Meta Tag Definition Files

Application-specific Custom Meta Tags

For information about Tango applications, see the Application Server Getting Started Guide or Chapter 24 of the User's Guide.

In order to use application-specific custom meta tags, the system administrator must set the value of the customTagsPath configuration variable in application scope when setting up an application. Application-specific custom meta tags are loaded when that application is started; that is, when a Tango application file in the application is called.

Custom Meta Tag Example: tabletag.xml

You create custom meta tag definition XML files based on the annotated custom meta tag definition file (see Custom Tag Definition File Format). This section describes an example of the files necessary to create and use a custom meta tag.

1. Defining the Custom Meta Tag

tabletag.xml defines the <@TABLE> custom meta tag with the following syntax:

<@TABLE the_array=arrayname[BORDER=num] [CELLSPACING=num] [CELLPADDING=num] [HEIGHT=num/percent] [WIDTH=num/percent] [BGCOLOR=color] [BGCOLOR2=color]>

2. Installing the Custom Meta Tag

The custom tag definition file must be put into the folder specified by the customTagPath configuration variable, for either application or system scope.

To use the <@TABLE> custom meta tag in your application files, you load the custom meta tag definition file by restarting Tango Server or executing the <@RELOADCONFIG> tag; in the case of applications, the tag definition file for that application is loaded when that application is created.

3. Installing the Object

The <@TABLE> custom meta tag calls a Tango class file named array_utils.tcf.

The array_utils.tcf class file must be installed in a directory where Tango Server looks for Tango class files. These directories are specified using the TCFSearchPath configuration variable.

These parameters map to the attributes displayed in the table.taf Results HTML:

The Format_array Results HTML is processed by Tango Server, and the results are displayed in the table.taf Results HTML, which is read by the Web browser when table.taf is executed.

<@ifempty "@@method$cellspacing"><@ELSE> cellspacing=@@method$cellspacing</@IF>

<@ifempty "@@method$cellpadding"><@ELSE> cellpadding=@@method$cellpadding</@IF>

<@if expr="!(@@method$alternate) and len(@@method$bgcolor)"> bgcolor=@@method$bgcolor</@IF>>

<TR ALIGN=center<@IF expr="@@method$alternate and ((<@currow> % 2) != 0)"> BGCOLOR=@@method$bgcolor<@ELSEIF

4. Using the Custom Meta Tag in a Tango Application File

The Tango application file, table.taf, contains an Assign action and Results HTML containing the <@TABLE> custom meta tag

Executing table.taf in your Web browser after the custom meta tag definition file and the object (in this case, a Tango class file) has been properly installed gives you the following result:

You could modify this example to allow users to specify other table attributes to be passed through to the Tango class file in the <@TABLE> custom meta tag.