Syntax
CALL "uthtmout.wbb",tpl$,text$,work$,linkexpr$
Description
This program is a high-level routine CALLed by uthtmfil.wbb, uthtmkey.wbb, and uthtmsel.wbb. It can also be CALLed by custom programs when single-file processing is inadequate. It merges Business BASIC data with HTML text and produces results in work$. The intent is to produce a standard HTML page, so no input fields are generated as with an input form. If an input form is desired, utfrmout.wbb is used.
The program is sensitive to the user-defined format attributes in the data template tpl$, as well as format tags in the text$ template. The template attributes are discussed in the Data Templates section. The data template specified can be filled by the CALLing program using data from a number of sources. In applications where multiple data templates do not share data field names, this program can be CALLed multiple times to produce a final HTML output, with different data merged on each CALL.
|
Parameter |
Description |
|---|---|
|
tpl$ |
Data template used as the source for data field names. It contains data types and user-defined formatting attributes. See the Data Templates section for additional information. |
|
text$ |
HTML text string that may contain any text, meta instruction, or field tag reference. It is evaluated and copied, with possible substitutions and insertions, into work$. |
|
work$ |
Returns the HTML result of merging text$ with data in tpl$. |
|
linkexpr$ |
Text string used to generate any href links from the records to another page. linkexpr$ may contain one or more link definitions to be used if any data field contains the @link lead-in option. If multiple link expressions are contained in linkexpr$, they must be separated by an ASCII character 1 - $01$. An example of a use for a link expression links a record in a list to a full-page display of that particular record. Typically, the full-page display is based on the record's key field. The following example assumes there is a script that will be given the records key through the ID field: linkexpr$="/cgi-bin/showpage?ID=[@encode ID]" If any link expression contains an ASCII 2 ($02$) character, the data before the $02$ is used as the "href" portion of the link, and data after the $02$ is added to the <a ...> tag after the "href=" element. This is helpful when specifying things such as target frames in a link. For example, if the link expression is "/cgi-bin/showpage?id=1"+$02$+"target=A", the generated tag would be "<a href="/cgi-bin/showpage?id=1" target=A>...</a>". |
Note that uthtmout.wbb is CALLed recursively to format the actual URL used in the link, so the same formatting information applies to text$ and linkexpr$.
Meta Instructions
{include filename} - loads the text file filename into text$. This method creates HTML template files and incorporates them in an application. filename must be accessible to Business BASIC.
{if datafield opr value} ... {end} - evaluates the expression datafield opr value. If it fails, any text between the if and end tags is suppressed. If the expression is valid, the tags are removed, but the text between them is retained. datafield can be either a field in the data template or a global string variable name. The operator opr can be >, <, =, >=, <=, <>, in, or !in. The "in" and "!in" operators perform position checks on text fields and values. If datafield is numeric in the template, then value must be a simple number. If datafield is defined with a user attribute of "date=format", then value should be a text date, such as "11/30/95". {if}{end} tags may be nested.
If datafield is not found in the data template and is not a global string variable, the meta instruction is retained in the text.
Note that datafield should not be enclosed by brackets, and there must be at least one space between datafield and opr, and opr and value.
Field Tags
Field tags are placed in text$ in the format [dataname format-control options].
dataname is a data template field name, or a global string variable name. If it is not found in either form, then it is retained for subsequent CALLs with other data templates.
format-control is an optional format control word used to indicate special formatting of the merged data. These values can optionally be placed before the dataname for compatibility with earlier releases. Valid values are:
|
@link or @linkn |
Creates an "<a href="url-value">data-value</a> expression from the dataname value. The format of the url-value is specified in the linkexpr$ variable. If multiple link formats are specified in linkexpr$, the format @linkn can be used, where n specifies the link format number to use with this dataname. |
|
@encode |
Forces the dataname value to be URL encoded. |
|
@image |
Causes an <img src="data-value"> tag to be generated from the dataname value. If the global string variable "$imageurl" is defined, it is used as a prefix to the dataname value. In addition, if the global string variable "$imagelib" is defined, it is used to locate the physical image file, if it resides on the host system, and determine the image dimensions for the <IMG> tag. |
|
@pad |
Ensures that a right padded, rather than trimmed dataname value is used. |
|
@lpad |
Ensures that a left padded, rather than trimmed dataname value is used. |
Padding is only necessary on pre-formatted output (such as between <pre> and </pre> tags.)
options may include:
keys="item1;item2;...;itemn"
vals="desc1;desc2;...;descn"
sep="char" or $hex$
alt="image-altname"
passthru=y or n
The "sep" option is used to define the separator character used in "keys" and "vals". By default, it is a semicolon, but may be set to any value, including nonprintable values, except a quote.
If keys and vals are specified, then the dataname value is compared to the list of item values, and the corresponding desc value is merged, rather than the dataname value itself.
If the @image lead-in option is specified, the image-altname is used to specify the "alt=name" in the HTML image tag. The default name is "image".
Normally, any dataname value that comes from the data template is modified for HTML markup entities. If passthru=y is specified, the utentity.wbb routine is not CALLed, allowing HTML text to be stored in the data template. The "passthru" user-defined attribute in the data template is overridden by any value specified in the options here.