Foundation Class Library (Java):

TemplateMapBasic is deprecated and is provided for backward compatibility only. New Java applications should use the standard servlet-JSP programming model.

For information about replacing TemplateMapBasic functionality in existing applications, see the Migration Guide.

The TemplateMapBasic class represents an object that contains one or more mappings between fields in an HTML template and the data used to replace those fields. It provides a method for defining these mappings before processing the template using evalTemplate( ) or evalOutput( ) in the AppLogic class (deprecated).

Fields in the HTML template are defined using special GX markup tags. The data, which the Template Engine uses to replace those fields dynamically at runtime, can come from any of the following sources: a calculated value, a column in a result set, a field in an ITemplateData template data object, or a field from a map object.

Before calling evalTemplate( ) or evalOutput( ) in the AppLogic class, an AppLogic uses the put( ) or putString( ) method in the TemplateMapBasic class to link the field name in the GX markup tag with a precomputed value or a named column or field in the data source. After defining the mappings, the AppLogic passes the populated ITemplateMapBasic object as the map parameter in evalTemplate( ) or evalOutput( ). The Template Engine uses these mappings during template processing to dynamically transfer data values from the data source to the HTML output report.

Mapping allows the AppLogic to use the same template for multiple data sources with different column names, for a data source whose schema changes over time, or for memory-based data sources defined using a TemplateDataBasic object.

To create a template map, use the GX CreateTemplateMapBasic( ) method, as shown in the following example:

TemplateMapBasic map = GX.CreateTemplateMapBasic();

To provide application-specific special processing, the AppLogic can subclass TemplateMapBasic and override its getString( ) method to hook into the Template Engine generation process. For example, AppLogic can intercept and filter data from a database before the Template Engine processes it.

Package
com.kivasoft.applogic

Methods


Method	Description
getString( )	Resolves the id attribute specified in a GX markup tag in the template being processed by the Template Engine. This method is called by the get( ) method in the ITemplateMap interface.
put( )	Maps the value assigned to the id attribute in the HTML template to another value. This method takes an IBuffer object (that contains a string expression) for the replacement value argument.
putString( )	Maps the value assigned to the id attribute in the HTML template to another value. This method takes a string argument for the replacement value.

Implements
ITemplateMap interface (deprecated)

Example

// Create template map

TemplateMapBasic map = new TemplateMapBasic();

[... create a query ...]	

// map columns in table to tags in template

map.putString("ParentsSelect", selStr);

map.putString("NAME", myName);

map.putString("CATEGORY", catStr);

// Evaluate the return template using the column mappings

if(evalTemplate(HTML, (ITemplateData) null, map)==0)

   return result("");

else

   return result("Failed to Generate HTML");

getString( )
Resolves the id attribute specified in a GX markup tag in the template being processed by the Template Engine. This method is called by the Template Engine.

Syntax

public String getString(
	String szExpr,
	IObject pData,
	IObject pMark)

szExpr. In the current GX markup tag in the HTML template being processed, the name of the field, or placeholder, assigned to the id attribute. Must be an identical match (case-sensitive).

pData. Specify null.

pMark. Specify null.

Usage
GX markup tags are used in an HTML template to identify where dynamic data appears in the output report. In the GX markup tags, the id attribute specifies any of the following items: the name of a flat query within a hierarchical query, a field in the hierarchical result set or TemplateDataBasic object, or an HTML template. The type of item specified in the id attribute depends on the type attribute that is specified in the same GX markup tag.

To provide application-specific special processing, an AppLogic can subclass the TemplateMapBasic class (deprecated) and override getString( ) to manipulate the Template Engine generation process. For example, an AppLogic can intercept and filter data from a database before the Template Engine processes it.

Rule
An AppLogic should use getString( ) only to override it after subclassing the TemplateMapBasic class (deprecated).

Return Value
A string that contains the value of the id mapping, or null for failure.

Example
The following code shows how getString( ) in a custom template map class is overridden to recalculate the current time each time it is encountered in a template:

import com.kivasoft.*;

class myTMB extends TemplateMapBasic {

   public String getString(String key, data, mark)

   {

      if (key.equals("CURTIME"))

         return new Date().toString();

      return super.getString(key, data, mark);

   }

}

put( )
Maps the value assigned to the id attribute in the HTML template to another value. This method takes an IBuffer object that contains a string expression for the replacement value.

Syntax

public int put(
	String szExpr,
	IBuffer pBuff)

szExpr . In the GX markup tag in the HTML template, the name of the field, or placeholder, assigned to the id attribute. Must be an identical match (case-sensitive).

pBuff. IBuffer object that contains the String expression to substitute for the specified template field name, such as:

Calculated value, such as a number or date.

Name of the column in the hierarchical result set that the Template Engine uses to process the template. In your template, the column name must begin with a "$" character.

Name of a field in the TemplateDataBasic object that the Template Engine uses to process the template. In your template, the field name must begin with a "$" character.

Usage
Use put( ) to add template field/data source pairs to the template map before calling evalTemplate( ) or evalOutput( ) in the AppLogic class.

Tips

To create an IBuffer object that contains the string expression to pass to put( ), use GX.CreateBufferFromString( ). Alternatively, use putString( ) to pass a string directly.

The AppLogic can place the put( ) method call inside a loop to construct the field map iteratively. For example, the AppLogic could use this technique to populate a map from a file, line by line.

Return Value
GXE.SUCCESS if the method succeeds.

putString( )
Maps the value assigned to the id attribute in the HTML template to another value. This method takes a string argument for the replacement value.

Syntax

public int putString(
	String szExpr,
	String szData)

szExpr. In the GX markup tag in the HTML template, the name of the field, or placeholder, assigned to the id attribute. Must be an identical match (case-sensitive).

szData. The String expression to substitute for the specified template field name, such as:

Calculated value, such as a number or date. Use the string.valueOf( ) methods to convert calculated values to a string.

Name of the column in the hierarchical result set that the Template Engine uses to process the template. In your template, the column name must begin with a "$" character.

Name of a field in the TemplateDataBasic object that the Template Engine uses to process the template. In your template, the field name must begin with a "$" character.

Usage
Use putString( ) to add template field/data source pairs to the template map before calling evalTemplate( ) or evalOutput( ) in the AppLogic class.

Tip
The AppLogic can place the putString( ) method call inside a loop to construct the field map iteratively. For example, the AppLogic could use this technique to populate a map from a file, line by line.

Return Value
GXE.SUCCESS if the method succeeds.

Example

// Create template map

TemplateMapBasic map = new TemplateMapBasic();

[... create a query ...]

// map columns in table to tags in template

map.putString("ParentsSelect", selStr);

map.putString(ICatalogData.COL_NAME, myName);

map.putString(ICatalogData.COL_CATEGORYID, catStr);



// Evaluate the return template using the column mappings

if(evalTemplate(HTML, (ITemplateData) null, map)==0)

   return result("");

else

   return result("Failed to Generate HTML");

TemplateDataBasic class (deprecated)

ITemplateData interface (deprecated)

ITemplateMap interface (deprecated)