Introduction

CopiaFacts has the ability to control the inclusion of blocks of text using variables, in the following file types:

HTML files converted to TIF or PDF using the Document Converter.

E-mail body and alternate body files.

E-mail HTML attachments.

SMS message bodies.

ASCII files converted to TIF using ASCII_TEMPLATE.

XML files used for Text-to-Speech prompts

Blocks of text to be conditionally included must consist of whole lines of text: there is no means to control the inclusion of part of a line.  However with HTML text, line-breaks in the file are usually not significant.

Syntax

The commands used to control text inclusion are the same conditional commands normally used in infoboxes to control scripting tasks:

The conditional commands $if, $ifn, $ife, $ifne, $else, $elseif and $endif condition blocks of text.  If-blocks may be nested to any depth (though the limit remains 32 levels in infobox files).

The loop commands $repeat, $until and $break allow blocks of text to be repeated.  This feature is not available in ASCII_TEMPLATE operations.

A subset of the $set_var command options allow loop variables to be maintained and new variables defined.  This feature is not available in ASCII_TEMPLATE operations.

The variable-introducing character on these commands is always the 'e-mail macro character' which defaults to ` (accent grave).  This applies even if the expansion character for the included text (in the case of ASCII files) is the standard @ character.

For e-mail body and SMS body conditional text, the text is processed after it has been built from separate 'body' and 'text' commands.

For ASCII files being converted to TIF, conditional text processing is suppressed by ASCII_NO_EXPAND.

For $set_var commands, the assignments available are as in the following examples:

Plain assignment:$set_var varname2 `varname1
Concatenation:$set_var varname2 |`varname1
Arithmetic:$set_var loop +1

Variables created or assigned by $set_var commands can also be used in the conditional text.

Enabling Conditional Text

This feature is normally not enabled.  To enable it for a specific job or FS file, define a variable CONDITIONAL_TEXT with a value containing one or more of the following keywords:

HTMLApply conditional text for HTML files expanded with the $job_options keyword HtmlExpandVars
EMAILBODYApply conditional text for e-mail bodies
EMAILALTApply conditional text for e-mail alternate bodies
EMAILATTApply conditional text for e-mail attachments with content-type text/html
SMSApply conditional text for SMS message texts
ASCIIApply conditional text for faxed ASCII files
TTSApply conditional text for Text-to-Speech XML files

As with the infobox commands, there is a default limit of 256 times for the expansion of repeat-until blocks.  You can vary this limit by defining a variable CONDITIONAL_LIMIT containing a different limit.

These variables must be visible from the FS file initiating the text operation, but may also be defined in its USR/UJP file or in FAXFACTS.CFG.

Testing the Text File Conditions

It is important that the commands in the text file have correct syntax.  Syntax errors such as 'else without if' are detected and reported in the trace file, but may result in an incomplete or erroneous output text, or for some error cases the output of the whole text including the conditional statements. The operation using this feature will fail if there is a serious syntax error.

The FFTESTCT program is provided to test the operation of conditional text statements.  It can load an FS containing variable definitions, and the text file to be processed, and then display the output resulting from the conditional processing.  If started with parameters, the first or only parameter is the FS file and the second is the text file.  You can edit the text in either file to test various conditions.

Example

User Profile or FS file:

$var_def CONDITIONAL_TEXT "html ascii"

Text file:

$if `BCF3 = NJ

Include this text for items where column 3 in the list is NJ

$elseif `BCF3 = NY

Include this text for items where column 3 in the list is NY

$endif