The Component Template File

A component template specifies the name, type, and initial state of all the component’s attributes with the FrontPage Bot Template Language (BTL, or “bottle”). This is the same format used to store the persistent state of a FrontPage component instance after it is inserted on a page. The presence of BTL on a page is what distinguishes SmartHTML from HTML.

Here is a simple example component described in BTL to refer to as you read this section:

<!--WEBBOT BOT=SampleBot S-PARAM1="This is a string" -->

BTL Syntax

FrontPage component templates and instances stored in BTL are legal HTML comments. They begin with the string <!--WEBBOT and end with the string -->. No white space is allowed between the opening <!-- and WEBBOT, which must be all upper-case. There must be at least one white space character before the closing -->. HTML allows white space between the final -- and the >, but BTL does not.

Between the delimiters are one or more space-separated attributes which have essentially the same syntax as the attributes of an HTML tag. The attributes are name-value pairs with an equal sign between the name and the value. White space is allowed around the equal sign. The name begins with a letter and is followed by up to 71 letters, digits, periods, or hyphens. The name is case-insensitive. The value may be either a string literal enclosed in double quotes or a name token (with a leading digit allowed). Some attributes may consist of a name only with the equal sign and value omitted.

String literals may not contain a double-quote, ampersand, or greater-than character, but they may include new-lines. To include a quote, ampersand, or greater-than character in a string-literal, escape it using HTML syntax: For example:

"You must escape the &quot; &amp; and &gt; characters"

The first attribute of a component must be BOT=shortname. The shortname may be written in mixed case for readability, but it is case insensitive; MACRO, Macro, and macro refer to the same type of component.

Repeated attributes with the same name but different values are allowed, this is how components can store arrays of values. For example:

<--WEBBOT BOT=ClickImage RECT="10,10,50,20" RECT="10,30,50,20" -->

Components are not allowed inside an HTML tag (for example as the value of an HREF attribute), but otherwise components are allowed anywhere in the HTML stream that the text returned by the component’s evaluate method would be allowed.

HTML comments (and thus components) do not generate any white space when processed. Thus:

some<!--WEBBOT BOT=NoOpBot -->pig

will be displayed as somepig by the editor or a browser.

Reserved BTL Attributes

Certain reserved attributes have special meanings that are understood by the generic FrontPage Component Properties dialog. These reserved attributes are not required, but if present must be used as described below. Other attributes have a leading character and a dash in their name to indicate their data type. This information is used by the generic FrontPage Component Properties dialog to display type-appropriate controls for modifying the attribute’s value.

The following table summarizes the reserved BTL attributes and what they mean:

attribute meaning
NAME A short user-readable name for the component type. Often just the shortname with spaces, i.e. BOT=TextSearch NAME="Text Search". This defaults to the shortname
TAG The HTML tag type returned by the Evaluate method of the component. The value should be a valid HTML tag (with no < or >; example: TAG=H3). If TAG is not provided, the component should evaluate to plain text with no embedded HTML tags.
PREVIEW A preview string, possibly containing some HTML tags. If present, the FrontPage Editor uses this as the edit-time representation of the component. If it is missing (and the component is unknown), the FrontPage Editor displays the component name in a pair of square brackets, like this: [WebBotName]

If a TAG is provided, then the PREVIEW string must match the tag type. For example, if TAG=H2, then a valid PREVIEW string would be something like “<H2>Test Component</H2>”.

The PREVIEW string must have any embedded <, &, >, and “ characters properly escaped. The previous example would be stored in BTL file as:

PREVIEW="&lt;H2&gt;Test Bot&lt;/H2&gt;".

DESCR A short (one or two sentences at most) description of what the component is and does. This is displayed by the generic FrontPage Component Properties dialog. Extra white space and new lines are removed from the description string before it is show to the user.
HELP A slightly longer (a paragraph or two at most) description that is displayed when the user clicks the Help button in the generic FrontPage Component Properties dialog. Extra white space and new lines are removed from the help string before it is shown to the user. To force a new line, put \n in the string. Use \\ for a single back-slash.

Reserved BTL attributes

BTL Data Type Encoding

Component attributes that are user-editable should begin with a letter that specifies the data type of the attribute’s value, followed by a dash. For example, an integer parameter named count would be represented as “I-Count=23”.

The main data types supported by the generic FrontPage Component Properties dialog are:

code data type
I Integer
S String
B Boolean (TRUE or FALSE)
D Date (in RFC-1123 format)
U URL (a reference to a document in the same web)
C Color (in HTML hexadecimal format: “#ff00ff”)

Basic data types supported by the generic FrontPage Component Properties dialog

When attribute names are displayed to the user, the leading data-type letter and dash are removed, and dashes are converted to spaces. For example, I-Maximum-Matches becomes “Maximum Matches.”

There are three additional attribute name prefixes which change the way a value is modified with the generic FrontPage Component Properties dialog: MIN-, MAX-, and RADIO-.

The prefixes MIN- and MAX- allow the component to specify a range of legal values for integer attributes, and a minimum and maximum length for string attributes. For example, the component could contain:

I-COUNT=10 MIN-COUNT=0 MAX-COUNT=255

The prefix RADIO- allows the component to specify that a parameter represents a one-of-many choice. Each subsequent RADIO- modifier supplies another legal value for that parameter. For example:

S-FLAVOR="Vanilla" RADIO-FLAVOR="Vanilla" RADIO-FLAVOR="Chocolate"

Any other attributes which encode the persistent state of the component but are not user-editable must not have a dash anywhere in their name.