HTMPL Tags

This article contains the following topics:
casm1401
This article contains the following topics:
This section outlines PDM commands to add HTMPL tags.
PDM_EVAL - Insert the Value of a Pre-Processor Variable
The pdm_eval tag is used to insert the value of a pre-processor variable into the input of the webengine parser. If used inside a macro, its effect is deferred until the macro completes.
The pdm_eval tag works similarly to pdm_include or pdm_macro. It inserts the text into the parser at the point of the tag, exactly as if the value of its variable had been coded in place of the tag.
pdm_eval has the following syntax:
<PDM_EVAL TEXT=PRE.name>
  • name
    (Required) The name of the pre-processor variable whose value is to be inserted into the webengine’s input.
PDM_FORM - Start an HTML Form with a Session ID
<PDM_FORM> and </PDM_FORM> can be added to any web interface HTML template to create an HTML form including two hidden fields for the server variables SID (session ID) and FID (form ID). The optional OP operand creates an additional hidden field for one of the supported operations, as with the PDM_LINK tag. Except for the automatically-generated hidden fields, <PDM_FORM> and </PDM_FORM> are used in the same way as the standard HTML <form> and </form> tags (and generate these tags as part of their expansion).
PDM_FMT - Format Text from a Server Variable
The <PDM_FMT> and </PDM_FMT> tags are used to format blocks of text inserted by server variables ($args.xxx) as directed by its arguments.
<PDM_FMT> is ignored for literals, including $prop.xxx variables.
The following table describes these tags:
Property
Description
ESC_STYLE=
NONE
|
C |
HTML |
JS |
JS2 |
URL
Specifies the escape type of the formatted text. Valid values are:
NONE
Default setting. Specifies that no special treatment be given to any character in the content body.
C
Give special treatment to the characters ', ", \, \r, `, and \n, which are meaningful in C programs. These characters will be escaped.
HTML
Give special treatment to the following characters, which are meaningful in HTML text:
& becomes &amp;
' becomes &apos;
" becomes &quot;
< becomes &lt;
> becomes %gt;
JS
Give special treatment to the following characters, which are meaningful in JavaScript text:
' becomes %27
" becomes %22
/ becomes %2F
\ becomes %5C
\r becomes %0D
\n becomes %0A
JS2
Same as JS, but give no special treatment to the character, /, and give special treatment to two additional characters:
- % becomes %25
- Line breaks are suffixed with %0A
URL
Translate all characters other than letters, digits, and '@*-_.#' to '%xx', where xx is the hexadecimal coding of the translated character.
JUSTIFY=LEFT |
CENTER |
RIGHT |
TRUNCATE
|
WRAP |
LIN
Specifies the justification of the formatted text. Valid values include:
TRUNCATE
Default setting. Eliminates HTML formatting by replacing '<' and '>' with &lt; and &gt;
Note:
For more information, see the following information about KEEPLINKS and KEEPTAGS.
LEFT|CENTER|RIGHT
Produces exactly WIDTH characters, truncated or padded with spaces as necessary, with any embedded new lines replaced by a single space, and the output text delimited by [set the pre variable for your book] and </pre> tags. The WIDTH argument must be specified as a positive integer.
WRAP
Same as LEFT, except that text wrapping honors word boundaries (line breaks are not placed within words).
LINE
Same as TRUNCATE, except that it also replaces all embedded line breaks with <br> tags.
KEEPLINKS=YES|
NO
If KEEPLINKS=YES is specified, the action of JUSTIFY=LINE or JUSTIFY=TRUNCATE is modified to preserve HTML anchor tags (Action:) while converting all other '<' and '>' characters. Mutually exclusive with KEEPTAGS.
KEEPNL=YES|
NO
The normal action of PDM_FMT is to convert all embedded new lines and any following spaces to a single space. If KEEPNL=YES is specified, embedded new lines are preserved. This argument is ignored for JUSTIFY=LINE.
KEEPTAGS=YES|
NO
If KEEPTAGS=YES is specified, the action of JUSTIFY=LINE or JUSTIFY=TRUNCATE is modified to preserve all HTML tags. Mutually exclusive with KEEPLINKS.
PAD=
YES
|NO
If PAD=NO is specified, PDM_FMT does not convert empty strings to a single space. This is the normal action when WIDTH is non-zero, or JUSTIFY is TRUNCATE or WRAP.
WIDTH=
nn
When non-zero, specifies that the text should be formatted to exactly WIDTH characters.
<PDM_FMT> without WIDTH or JUSTIFY does no formatting on the enclosed text, but surrounds the text with [set the pre variable for your book]and </pre>.
For example, to produce a multi-line description, enter the following:
<PDM_FMT WIDTH=50 JUSTIFY=WRAP>$args.description</PDM_FMT>
To produce multi-column output, enter the following:
<PDM_FMT><PDM_FMT WIDTH=20 JUSTIFY=LEFT>$cst.last_name</PDM_FMT> <PDM_FMT WIDTH=20 JUSTIFY=LEFT>$cst.first_name</PDM_FMT> <PDM_FMT WIDTH=20 JUSTIFY=TRUNCATE>$cst.middle_name</PDM_FMT> </PDM_FMT>
PDM_IF - Conditional Processing
These tags are used to conditionally include text. <PDM_IF> blocks can be placed anywhere in an HTMPL file - in HTML, in JavaScript, and even within HTML tags. <PDM_IF> and <PDM_ELIF> (else if) both take a simple conditional clause as their properties rather than name-value pairs. If the clause is true, the text after the tag to the closing tag is included in the file; if the clause is false, the server discards the text between the tag and the closing tag. The closing tag can be <PDM_ELIF>, <PDM_ELSE>, or </PDM_IF>.
The <PDM_ELSE> and <PDM_ELIF> tags are optional. If both are specified, all <PDM_ELIF> tags must precede <PDM_ELSE>. There can be any number of <PDM_ELIF> tags between <PDM_IF> and <PDM_ELSE> (or </PDM_IF> if <PDM_ELSE> is omitted).
The syntax of the conditional in <PDM_IF> and <PDM_ELIF> is as follows:
  • 0 is false; any other number is true
  • ““ is false; “
    any
    -
    string
    ” is true
  • value op value
    ” evaluates the left and right values against each other according to
    op
    . If both values consist of digits (optionally preceded by - or +), the comparisons are done numerically. Otherwise, they are done lexically (ASCII collation). Valid
    op
    values include:
op Value
Description
==
Equal to
!=
Not equal to
>=
Equal to or greater than (must be written as \>= or &gt;=)
<
Less than (must be written as \< or &lt;)
>
Greater than (must be written as \> or &gt;)
<=
Equal to or less than (must be written as \<= or &lt;=)
&
Performs a bit-and of the left and right values. True if any bits are set; false if none are set.
%
Returns true if the left value is an even multiple of the right value, and false otherwise (useful for building two-dimensional tables).
:
Performs a byte-oriented pattern match like the UNIX grep command. It returns true if the left value contains the regular expression defined by the right value.
Example:
<PDM_IF $count \>= 10> . . . <PDM_ELIF $count &#60; 5> . . . <PDM_ELSE> . . . </PDM_IF>
There can be more than one conditional in a PDM_IF statement. Conditionals are separated by connectors, either && (and) or || (or). There is no precedence for either connector. The web engine examines a conditional from left to right until it reaches a connector. If the initial condition is true and the connector is ||, it considers the entire condition to be true without further evaluation. If the initial condition is false and the connector is &&, it considers the entire condition to be false without further evaluation. Otherwise, it considers the condition undetermined, and evaluates the conditional from after the connector.
PDM_INCLUDE - Inserting from a Different File
The <PDM_INCLUDE> tag is used to insert text from a second file into an HTMPL file. The server replaces the <PDM_INCLUDE> tag with the contents of the second file.
Included files can contain <PDM_INCLUDE> tags. There is no limit to the depth of nesting.
The <PDM_INCLUDE> tag supports the following properties:
Property
Description
FILE=filename
(Required) Specifies the file to include. The web engine searches the directories used for HTMPL files, as defined in the current user's access type.
FIXUP=[
YES|
NO]
(Optional) Indicates whether the file should be interpreted by the web interface like a normal HTML template file, such as expanding variables beginning with dollar signs ($) and interpreting other CA SDM tags, such as PDM_LIST, and PDM_FORMAT. The value YES, indicates that the file should be treated as a regular HTML template file, and the value NO means that the included file should be treated as literal text. The default is YES.
Note:
For compatibility with previous releases, the values TRUE or 1 can be substituted for YES, and the values FALSE or 0 can be substituted for NO. These values are deprecated, and should not be used in new pages.
propname=value
Specifies that property propname should have the specified value. The property's value can be accessed within the included file by prefixing propname with $prop. For example, the following specification would allow the included file to reference $prop.menubar:<PDM_INCLUDE … menubar=no>
Global properties can also be specified in the web.cfg configuration file. For information about web.cfg, see How to Configure the Web Interface.
Note:
For compatibility with previous releases, property values specified on <PDM_INCLUDE> can be referenced without the preceding 'prop.', in the form $propname. This usage is deprecated and should not be used in new pages.
PDM_JSCRIPT - Conditionally Include a JavaScript File
The <PDM_JSCRIPT> tag is used to conditionally include a JavaScript file on a form. This tag has two forms:
<PDM_JSCRIPT file=xxxx.js [include=yes|no]>
Pdm_jscript with file=xxx.js specifies that JavaScript file xxx.js is required by this form. The webengine adds the file to a list of JavaScript files required by the form. Processing of the tag occurs while the form is being parsed, and is not affected by pdm_if. That is, a pdm_jscript tag referencing a file adds that file to the list of JavaScript files if it occurs anywhere in the file or in an included file, or in a macro.
The optional argument
include=no
can be specified to instruct the webengine to ignore the tag. This argument provides conditional processing for the tag, and is primarily useful when the tag is invoked in a macro. For example, the dtlTextbox macro specifies the following:
<PDM_JSCRIPT file=spellcheck.js include=&{spellchk}>
This indicates that any form containing a dtlTextbox macro that specifies spellchk=yes requires the JavaScript file spellcheck.js.
The second form of the pdm_jscript tag is the following:
<PDM_JSCRIPT insert=here>
Pdm_jscript with insert=here requests the webengine to insert standard HTML <script> tags for all required JavaScript files. The webengine processes this form of the tag during the HTML generation phase, so that it is affected by pdm_if. A pdm_jscript tag with insert=here is part of std_head_include.htmpl, so it is present on virtually every form.
The webengine inserts script tags only the first time it encounters pdm_jscript insert=here.
PDM_LINK - Create a Hyperlink Invoking an HTMPL Operation
<PDM_LINK> and </PDM_LINK> can be added to any web interface HTML template to create links a link that invokes an HTMPL operation. The <PDM_LINK> tag generates the standard HTML <a href=...> tag and has similar arguments, except that it allows specification of a CA SDM operation in place of a URL.
The format is as follows, where
operation
is one of the supported operations:
<PDM_LINK OP=operation> ... </PDM_LINK>
Example:
<PDM_LINK OP=MENU> Menu </PDM_LINK> <PDM_LINK OP=CREATE_NEW FACTORY=iss> Submit Issue </PDM_LINK> <PDM_LINK OP=LOGOUT> Logout </PDM_LINK>
PDM_LIST - Format a List of Database Rows
The <PDM_LIST> and </PDM_LIST> tags are used to delimit repeating sections of HTML for multi-record output. Everything between <PDM_LIST> and </PDM_LIST> is repeated once for each record to be output. There are two types of PDM_LISTs:
  • Lists taken from an object attribute that implies a list. For example, the properties attribute of the request object is the list of properties associated with that request. This type of PDM_LIST always has a SOURCE property.
  • Lists with an explicit where clause. This type of PDM_LIST always has a WHERE property.
An object attribute <PDM_LIST> takes the following properties:
Property
Description
ESC_STYLE=
NONE
|
C |
HTML |
JS |
JS2 |
URL
Specifies the escape type of the formatted text. Valid values are:
NONE
Default setting. Specifies that no special treatment be given to any character in the content body.
C
Give special treatment to the characters ', “, \, \r, ', and \n, which are meaningful in C programs. These characters will be escaped.
HTML
Give special treatment to the following characters, which are meaningful in HTML text:
& becomes &amp;' becomes &apos;" becomes &quot;< becomes &lt;> becomes %gt;
JS
Give special treatment to the following characters, which are meaningful in JavaScript text:
' becomes %27" becomes %22/ becomes %2F\ becomes %5C\r becomes %0D\n becomes %0A
JS2
Same as JS, but give no special treatment to the character, /, and give special treatment to two additional characters:
- % becomes %25
- Line breaks are suffixed with %0A
URL
Translate all characters other than letters, digits, and '@*-_.#' to '%xx', where xx is the hexadecimal coding of the translated character.
LENGTH=
nn
Specifies the number of rows of output (defaults to all).
PREFIX=
prefix
Specifies the prefix on references to attributes from records in the list. These are referenced in the form
$prefix.attr_name
in the text between <PDM_LIST> and </PDM_LIST>. The PREFIX property is optional in an object variable list. If PREFIX is omitted, the value of SOURCE is also used for the prefix.
SEARCH_TYPE=DISPLAY|
GET_DOB
Specifies the method the server should use to build the list form:
DISPLAY specifies the server should issue a single query for the entire form
GET_DOB specifies the server should issue separate queries for each row of the form
The choice affects list performance, and depends on the complexity of the list (the number of joins required to display it) and the characteristics of your DBMS. GET_DOB has more predictable performance than DISPLAY, and is the default.
SORT=
index
-
name
Specifies the index name to use for sorting. The default value of this argument is DEFAULT (which means the first sort index for the underlying factory).
SOURCE=
source
Specifies the object variable defining this list. This field is required. Do not put a dollar sign ($) in front of
source
on the PDM_LIST statement itself. If the PREFIX property is not specified,
source
is also used as the prefix for references to attributes from records on the list, in references of the form
$source
.
attr_name
. When used in a reference,
source
does require a preceding dollar sign.
START=
nn
Specifies the first output row (defaults to zero).
Example:
<table border> <tr> <th>Child Change Order Number</th> <th>Summary</th> </tr> <PDM_LIST SOURCE=args.children> <tr> [assign the value for TD in your book]$args.children.chg_ref_num</td> [assign the value for TD in your book]$args.children.summary</td> </tr> </PDM_LIST> </table>
Because no prefix was specified, references to attributes of the listed records are prefixed by $args.children, the source value.
A where clause PDM_LIST takes the following properties:
Property
Description
FACTORY=
name
Specifies a class of object to be searched. This property is required.
LENGTH=
nn
Specifies the number of rows of output (defaults to all).
ORDER_BY=
attr-name
Specify the attribute name to sort by. It can contain the DESC (descending) or ASC (ascending) modifiers.
PREFIX=
prefix
Specifies the prefix on references to attributes from records in the list. These are referenced in the form
$prefix
.
attr_name
in the text between <PDM_LIST> and </PDM_LIST>. The PREFIX property is required in a where clause list.
START=
nn
Specifies the first output row (defaults to zero).
WHERE=
where-clause
Specify the where clause for the search. It can contain (dotted) attributes. This property is required.
For example:
<table> <tr> <th>Child Change Order Number</th> <th>Summary</th> </tr> <PDM_LIST PREFIX=list FACTORY=chg WHERE="status = 'OP'"> <tr> [assign the value for TD in your book]$list.chg_ref_num</td> [assign the value for TD in your book]$list.summary</td> </tr> </PDM_LIST> </table>
PDM_NOTEBOOK - Create a Notebook
Several of the forms in the CA SDM analyst interface use nested tabs (notebooks). Nested tabs display several sets of fields in the same physical area of the screen, with only one set visible at a time. The user selects the set of fields that is visible by clicking a named tab at the top of the notebook, or by pressing the access key combination Alt+
n
, where
n
is the number of the tab. An example of a form using a notebook is the Issue Detail (detail_iss.htmpl). We recommend that you use WSP to modify the contents of notebooks, or insert a notebook into a form that does not already contain one.
The following tag marks the end of a notebook:
<PDM_MACRO name=endNotebook>
PDM_PRAGMA - Specify Server Information
The <PDM_PRAGMA> tag is used to specify information used by the web engine, such as form release and version. It does not generate any HTML code, and can be placed anywhere in a form. Possible arguments are:
Argument
Description
RELEASE=value
Specifies the CA SDM release number corresponding to this form. This value is “110” on all CA Service Desk Manager r11.0 forms. It is accessible within the form in the $prop.release variable.
SITEMOD=value
Specifies a site-defined string identifying the modifications applied to this form. It is accessible within the form in the $prop.sitemod variable.
VERSION=value
Specifies a CA Technologies-defined string identifying the version number of this form. It is accessible within the form in the $prop.version variable.
OVERIDE=YES|
NO
Specifies whether or not values in this PDM_PRAGMA statement override values in previous PDM_PRAGMA statements.
CA Technologies uses PDM_PRAGMA statements to document form versions. All CA Service Desk Manager r11.0 forms include the following PDM_PRAGMA statement:
<PDM_PRAGMA RELEASE=110>
In addition, the std_head.htmpl form includes the following JavaScript statement:
cfgFormRelease = "$prop.release" - 0;
The PDM_PRAGMA statement and the cfgFormRelease variable allows the CA SDM web interface to distinguish CA Service Desk Manager r11.0 forms from previous release forms. Releases prior to CA Service Desk Manager r6.0 did not support the PDM_PRAGMA statement.
Normally, only PDM_PRAGMA statements in the highest-level file of a form (that is, a file not brought in by PDM_INCLUDE) are used to set $prop.release, $prop.sitemod, and $prop.version. In addition, a PDM_PRAGMA statement will not override a non-empty value set by a previous PDM_PRAGMA statement. You can specify OVERRIDE=YES to specify that a PDM_PRAGMA statement can override previous PDM_PRAGMA statements, or that a PDM_PRAGMA statement in an included file can be used.
PDM_SCOREBOARD - Build a Scoreboard Tree
The <PDM_SCOREBOARD> tag is used to generate the scoreboard shown on the left side of the main form. It takes the following property:
  • TARGET=
    value
    Specifies the name of the target frame for lists requested by clicking a node on the scoreboard. Lists are loaded into the target specified, which can be any value supported for the target attribute of a link. The default value is
    _self
    (the window containing the PDM_SCOREBOARD tag).
Any HTMPL form including a <PDM_SCOREBOARD> tag must also include the fldrtree.js JavaScript file. This file can be included with the following statement in <HEAD> section of the form:
<SCRIPT LANGUAGE="JavaScript" SRC="$CAisd/CAisd/fldrtree.js"></SCRIPT>
In addition, it is desirable to include a link with the name scoreboard_asof_data to display the effective date of the numbers in the tree. See the distributed file scoreboard.htmpl for an example of the use of this tag.
The queries included on the scoreboard are defined by the contents of the User_Query table (object name usq) for the current user. A record in this table defines each line on the tree (folder or node).
Initially, users have no entries in their User_Query table. A user with no User_Query entries receives the default set of scoreboard queries associated with their access type. A user with administrative authority can also customize the default scoreboard for an access type.
PDM_SET - Set the Value of a Server Variable
The
<PDM_SET>
tag is not supported for integer-based arithmetic operations like addition (for example:
<PDM_SET args.z_counter=$args.z_counter + 1>
).
It is only supported for setting a string property and string concatenation operation.
The <PDM_SET> tag is used to assign a value to a server variable. It has the following syntax:
<PDM_SET arg.name[+]=value>
  • arg
    (Required) Specifies the variable type, and must be arg for normal use.
    There is no $ character.
  • Name
    (Required) Specifies the name of the variable.
  • +
    (Optional) Specifies that the value should be appended to the existing value of the variable. There cannot be any spaces before or after.
  • =
    (Required) Must be specified exactly as shown, with no spaces before or after.
  • value
    (Required) Specifies the text to be assigned or appended to the variable.
The PDM_SET tag can also be used in the preprocessor phase to create or update a preprocessor variable.
PDM_TAB - Create a Tab within a Notebook
The <PDM_MACRO name=startNotebook hdr=cng_nb> tag is used to define a notebook tab. We recommend that you use WSP to modify the contents of notebooks, or insert a notebook into a form that does not already contain one.
PDM_WSP - Control WSP Preview
The <PDM_WSP> tag is used to control the WSP preview feature. It does not generate any HTML code, and can be placed anywhere in a form.
By default, WSP determines how to preview a form by examining the form name:
  • For detail forms (names of the form detail_
    factory
    .htmpl), WSP displays the form in edit view, with data from the most recently created row of the appropriate table. If there is no data you are allowed to view in the table, WSP displays the form set up to create a row. WSP preview sessions are typically prohibited from updating the database. WSP displays forms in edit view to allow you to preview all features. However, CA SDM ignores a Save request from a read-only preview session. The web engine changes the text on the Save button to noSave as a visual reminder of this.
  • For list forms (names of the form list_
    factory
    htmpl), WSP displays the form in list view, with the list displaying data from the most recently created row of the appropriate table. If there is no data you are allowed to view in the table, WSP displays the form in search view, with the filter open.
  • For other forms, WSP displays the form with no database context.
You can change this default behavior by placing a PDM_WSP tag anywhere on the form. For example, you can display a notebook tab form on its associated detail form, or provide prerequisite arguments for forms normally invoked with an environment provided by another form. Possible arguments are the following:
Property
Description
FACTORY=
value
Specifies the Object Engine factory used by this form.
PREVIEW=
name
.htmpl |
value
|
no
Specifies the preview URL. This can be an HTMPL file name, in the form xxxx.htmpl; a CA SDM URL (used unaltered if it begins with “OP=”); or the keyword “no”, indicating the form cannot be previewed. A value not beginning OP= is modified by replacing a reference of the form {
factory
} or {
factory
:} with an ID or persistent ID (respectively) of the most-recently created row from the referenced factory that the current user is authorized to view.
WHERE=
value
Specifies a where clause used to search for a representative row or rows to show on the previewed form.
MODE=
value
Specifies the mode of the constructed URL. Can be the following:
GENERAL. General format. Determine the mode by examining the preview argument:
detail_xxxx.htmpl - READONLY
list_xxxx.htmpl - LIST
any other - GRONK
READONLY. Detail file in read-only view.
EDIT. Detail file in edit view.
LIST. List file.
GRONK. Unspecified file. In this situation, gronk the file.