Server-Side Templates

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__
<BR><BR>
__DESCRIPTION.TEXT__
<BR>
</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 &nbsp; being rendered

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

  1. A stand-alone template that is used to simply format the results returned.

    Desired Output

    Template code

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

  2. 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.

    Desired Output

    Template code

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

    Header File

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



    Body File

    <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"><b>__SHORT_DESCR__</b></td>
    </tr>
    <tr>
    <td colspan="3">
    __REPEAT_START__
    __Description__
    __REPEAT_STOP__
    </td>
    </tr>



    Footer File

    </TABLE>
    <hr>
    <p><i><b>MyCo</b></i> - Your one stop shop for
    integrated data services<br>
    Powered by ExtraView</p>
    </body>
    </html>

    3. 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.

    Template file

    <html>
    <head><title>ExtraView Entry Details</title></head>
    <body>
    <hr>
    <p align=center>The ID for the problem is __ID__ and it was entered by
    __ANY_NAME_AT_ALL__.</p>
    <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.

    Template File

    <html>
    <head><title>ExtraView Error!</title></head>
    <body bgcolor="#cedece">
    <hr>
    <p align=center>__ERR_RESULTS__</p>
    <hr>
    </body>
    </html>

    Browser Output