Server-Side Templates – Product Documentation

Server-side templates can be defined for many API and CLI commands. These templates allow you to control the presentation of the output from the API command. Most commonly this is used to allow the administrator to integrate ExtraView with their company’s own web site.

For example, a page within your company’s web site can perform a search of the ExtraView database and return the results formatted with the same look and feel as the web site.

Templates allow you to use “tags” that are substituted at runtime, with the actual value in a record. For example, the tag __STATUS__ refers to the value of the STATUS field of the current issue. Tags are available for most fields in the data dictionary. In addition, if you place a data dictionary field on a template, it must exist on the Detailed Report layout inherited by the specific Business Area and Project. The user must also have read permission to the field.

TEXTAREA, LOGAREA and PRINTTEXT fields have special handling within ExtraView. This is because they can be broken down into three components, the text itself, the user’s name who entered the text, and a timestamp. Each of these components can be accessed individually, as shown in the following example. Note that the field name itself must be included as a tag, although it does not display anything in the output. Therefore, an HTML fragment that might display the DESCRIPTION field may look like:

<TD>
__DESCRIPTION__
__DESCRIPTION.USER__ : __DESCRIPTION.TIMESTAMP__
 
__DESCRIPTION.TEXT__
 
</TD>

The full explanation for each part of the field is as follows, where DDNAME is the data dictionary name of the field of display type TEXTAREA, LOGAREA or PRINTTEXT.

Field name	Explanation
__DDNAME__	A tag with the data dictionary name must be included in the template. No output occurs with this tag. It is a placeholder that ensures the remaining fields will be processed correctly
__DDNAME.TEXT__	This is used to return the body of text within the comments
__DDNAME.USER__	This is used to return the name of the user who entered the comment
__DDNAME.TIMESTAMP__	This is used to return the date (and time) that the comment was entered. This will be returned in the current user’s date and time format that is defined in their personal settings

Three special tags are not fields in the data dictionary:

Tag name	Explanation
__RESULTS__	this tag returns the result string that is sent, upon execution of a call to the API. For example, if you use an HTML form to insert a record into ExtraView, and define a template that contains only the tag __RESULTS__, then the output would be: Problem #12342 added.
__ERR_RESULTS__	this tag returns any error as a result of executing the API command. It is often used in conjunction with an error handling template, as described below
__RECORD_COUNT__	this tag returns the number of records found from the API action named search. You may use this field in the header or footer section of a template (see below), but not in the body part of a template.

The API commands that work with templates are:

delete
fill_in
get
insert
insert_user
list_attachment
search
update
update_user_password

The templates must be stored in a directory in your environment, typically located within your installation in a directory named user_templates. This directory is placed within your ExtraView installation, at the same level as the templates directory that resides inside the WEB-INF directory. This location may vary according to how you installed ExtraView. The ExtraView Administration screens have a feature that allows you to upload files directly to this directory from your local computer. Templates are processed slightly differently, according to whether they are intended to generate text or generate HTML. First, the assumption is that if the template name has a suffix of .html or .htm, then it is assumed that it will generate HTML code. With all other file suffixes, the assumption is that they contain text. If they are HTML templates:

The api calls search and get will have escaping enabled
Fields that have display_as_url set as attribute in the data dictionary will be rendered as HTML
Blank or null values in fields will result in   being rendered

The template you define can be in one of two forms:

Stand-alone templates, used to format the results

Desired Output

Sample Template Code

<html>
<head>
<title>ExtraView Insert Issue</title>
</head>
<body bgcolor=”#FFFFFF”>
Thank you for submitting your issue. It has been added to the tracking
database with the ID
 __ID__ 
Please take note of this number and use this if you wish to inquire
about the status.
</body>
</html>

Structured Formatting of Results

This is composed of a template structure that may have up to three sections, each of which resides in a separate file. Each file name is defined by prefixing the template name with the letter h, b or f, according to whether it is the header section, body section or the footer section. Each section is optional, although it makes no real sense to not have the body section.

Overall Desired Output

Sample Template Code

The template code is split into three files representing the fixed header, the repeating body and the fixed footer.

Header File – file name begins with “h”

<html>
<head>
<title>ExtraView Insert Issue</title>
</head>
<body bgcolor=”#FFFFFF” leftmargin=”0″ topmargin=”0″>
<img src=”MyCo.jpg” width=”1000″ height=”120″>
The results of your search found the following records 
<table width=”100%” border=”0″ cellpadding=”0″>

Body File – file name begins with “b”

<tr bgcolor=”#CCCCFF”>
<td>Issue Number</td>
<td>Status</td>
<td>Assigned To</td>
</tr>
<tr>
<td>__ID__</td>
<td>__STATUS__</td>
<td>__ASSIGNED_TO__</td>
</tr>
<tr>
<td colspan=”3″>__SHORT_DESCR__</td>
</tr>
<tr>
<td colspan=”3″> __REPEAT_START__ __Description__ __REPEAT_STOP__ </td>
</tr>

Footer File – file name begins with “f”

</TABLE>
<hr>
MyCo – Your one stop shop for integrated data services Powered by ExtraView
</body>
</html>

The fill_in Template

It is sometimes useful to be able to generate a template and populate it with values that do not originate in ExtraView’s database. The fill_in action fulfills this need.

Syntax

http://www.myserver.com/evj/ExtraView/ev_api.action?user_id=username &password=password&statevar=fill_in&p_template_file=this_template.html&id=12345 &any_name_at_all=Phyllis%20Mitchell … … …

The template file, this_template.html, will be returned to the user’s screen, with the values for id and any_name_at_all filled in.

Sample Template File

<html> <head> <title>ExtraView Entry Details</title> </head> <body> <hr> The ID for the problem is __ID__ and it was entered by __ANY_NAME_AT_ALL__. <hr> </body> </html>

Browser Output

The error.html Template

If the code that executes in the API command that was submitted completes with an error or unexpected condition, the template named error.html is invoked and used to display the error to the user. Within this template, the tag __ERR_RESULTS__ is replaced with the actual error message from the command being executed.

Sample Template File

<html>
<head>
<title>ExtraView Error!</title>
</head>
<body bgcolor=”#cedece”>
<hr>
__ERR_RESULTS__
<hr>
</body>
</html>