HTML Templates (HTMPL Form)

This article contains the following topics:
casm172
This article contains the following topics:
Forms in the CA SDM web interface are delivered as HTML templates, in files with a suffix of .htmpl. These are called HTMPL forms in the remainder of this document.
An HTMPL form contains standard HTML (including JavaScript) plus language extensions that are interpreted by a CA SDM server daemon (or service) called the web engine that delivers standard HTML to the browser. These extensions are:
  • References to server variables. These are indicated by a name beginning with a dollar sign. They can be the values of columns in the CA SDM database, references to web engine configuration properties, or other server information.
  • Special tags directing the web engine to perform tasks on the server, such as read information from the CA SDM database. These tags have names of the form <PDM_...> or <pdm_...>.
 You do not need to understand the HTMPL extensions or even HTML itself to be able to customize CA SDM forms with WSP.
Template Naming Conventions
The following naming conventions are used to identify the four basic types of HTMPL files, where
xxx
is the object:
Template Type
Name
List (search filter and results)
list_
xxx
.htmpl
Combined read-only and edit detail form (analyst interface)
detail_
xxx
.htmpl
Read-only detail form
detail_
xxx
_ro.htmpl
Edit detail form
detail_
xxx
_edit.htmpl
You can find the definitions of the objects and their properties in the following locations:
  • (UNIX) $NX_ROOT/bopcfg/majic/*.maj
  • (Windows)
    installation-directory
    \bopcfg\majic\*.maj
For information about the objects and attributes that define CA SDM, see CA Service Desk Manager Reference Commands.
HTMPL Directories
There are different sets of HTMPL files supplied to implement these interfaces, as shown in the following table:
Operating System
Directory Containing HTMPL Files
Windows
Installation-directory
\bopcfg\www\htmpl\web\
interface
UNIX
$NX_ROOT/bopcfg/www/htmpl/web/
interface
In this table,
interface
is the name of the interface (analyst, customer, or employee).
There is no separate directory for guest interface files; by default, this interface uses the employee interface files. You can change the guest user interface by changing the access type associated with user System_Anonymous. Both the customer and employee files dynamically modify themselves depending on whether the current user is a known user or a guest, using the <PDM_IF> template command described in this document.
There are three additional interface subdirectories under the htmpl directory:
  • default:
    Contains HTMPL files common to all interfaces. When searching for a file, the web engine looks first in the directory corresponding to the current user's interface, and then in the default directory.
  • pda/analyst: (UNIX)
  • pda\analyst: (Windows)
    Contains HTMPL files used by the mobile device interface. In CA Service Desk Manager r11.0, the mobile device interface is provided only for analysts.
  • web/
    interface
    /legacy: (UNIX)
  • web\
    interface
    \legacy: (Windows)
    Contains HTMPL files from your previous release of CA SDM that are no longer used. This directory is automatically created if you upgrade from a previous release when you install CA SDM. You can delete the legacy directory when none of its files are referenced by your customized files.
We strongly recommend that you do not directly modify the supplied HTMPL files. Instead, either use WSP, or manually copy the file you want to modify to the site mods directory, and modify it there. The CA SDM web server looks for a new form in the appropriate site mods directory before checking the distribution directory. The standard site mods directories for each of the interfaces are as follows:
Operating System
Directory For Site-Modified HTMPL Files
Windows
installation-directory\site\mods\www\htmpl\interface\interface
UNIX
$NX_ROOT/site/mods/www/htmpl/
interface/interface
If you change the form and save it into the
install directory\site\mods\www\htmpl\interface
directory, the form will be seen by everyone, regardless of the form group to which they belong. If you save it into the
install directory
\site\mods\www\htmpl\interface\
interface
directory, only those Contacts that are defined as belonging to that form group will see the changed forms.
In the previous table,
interface
is the name of the interface (analyst, customer, or employee). There is no separate directory for guest interface files; this interface uses the employee interface files. The advantage of storing your modified HTMPL files in the site mods directory is that this directory is preserved when you install CA SDM maintenance or a new release. In addition, keeping your modified files in site mods while preserving the originals ensures that you always have a correct copy of the originally distributed HTMPL file.
Each web interface page has a primary function, as indicated in the following table that lists the major HTML templates. However, you can add <PDM_FORM> blocks to any template to directly access any web interface supported operation. For example, you can modify the main menu to include fields for submitting an issue without using the intermediate page, or you can add search criteria fields and a search button to a list form:
Web Page
HTML Template
Main form
menu_frames.htmpl
Display/create/update a change order
detail_chg.htmpl
Display a list of change orders
list_chg.htmpl
Display/create/update and issue
detail_iss.htmpl
Display a list of issues
list_iss.htmpl
Display/create/update a request
detail_cr.htmpl
Display a list of requests
list_cr.htmpl
Display announcement detail information
detail_cnote_html
Display a list of announcements
list_cnote.html
Login
login.htmpl
For a complete list of templates, view the contents of the directories in the table at the beginning of this section.
Web Form Groups
You can collect customized web pages into one or more form groups. Form group directories are in the following directories:
  • Windows
    install-directory\site\mods\www\htmpl\web\
    interface
    install-directory\site\mods\www\wwwroot\subdirectory
  • UNIX
    $NX_ROOT/site/mods/www/htmpl/web/
    interface
    $NX_ROOT/site/mods/www/wwwroot/subdirectory
Each form group is a subdirectory under these directories. You specify the customized form directory in the Customization Form Group field of the access type.
When a user requests a form, the web engine looks first in the appropriate customized form group directory, then in the standard directory for the user's web interface, and finally in the default directory. You can define more than one access type for the same web interface, each with a different customized form group. This lets you define a few specialized forms for different types of users, and still take the majority of the forms from the standard interface.
A similar process occurs when a web page requests a file from one of the subdirectories of wwwroot (css, html, img, or scripts). The webengine examines an HTMPL reference of the form CAisd/img/xxx.gif and converts it to one of the following GIF files, selecting the first one where it finds xxx.gif:
  • /CAisd/sitemods/img/formgroup/xxx.gif
  • /CAisd/sitemods/img/xxx.gif
  • /CAisd/img/xxx.gif
How to Create a Web Form Group
You can create a web form group.
Follow these steps:
  1. If you want a form group besides the predefined Analyst, Customer, or Employee form groups, create a form group by selecting Save As from the File menu in WSP and clicking the Add Form Group button on the Save Form As dialog. For example, if you want to provide two separate customized versions of the Analyst interface, you might create form groups called Analyst1 and Analyst2 to handle these. You might also define a new form group if the interface you are defining does not logically fit into one of the predefined form groups.
  2. On the web interface (not a Web Screen Painter preview session), select Security, Access Types from the Administration menu. Then click an access type (or create one) and use the Customization Form Group drop-down list on the Access Type Detail window to assign a form group to an access type. CA SDM determines the access type when a contact logs in and uses customization form group to determine where to look in the site mods directory structure for customized forms. If the web engine does not find a form in the form group directory, it looks first in the standard directory for the user's access type, and then in the default directory.
  3. In WSP, select Save from the File menu, or manually copy the customized HTMPL files to the following directory:
    In Windows:
    installation-directory
    \site\mods\www\htmpl\web\
    form_group_name
    directory
    In UNIX: $NX_ROOT/site/mods/www/htmpl/web/
    form_group_name
After you set up a new web form group and copied any supporting files to the appropriate subdirectories, you must restart the web service before the changes take effect.