Web Form Declarations

A form declaration consists of a form name with an optional form attribute and a list of form fields.

The form name can be any valid identifier string, for example FORM_NAME. If an attribute is specified, it must consist of an identifier within angle brackets, for example < ENCODE_ESCAPE >. The form name must be separated by a colon from the list of form fields.

The subsequent list specifies the fields of a web form or the parameters of a URL string. The string or variable on the left specifies the name of the field or parameter. An empty string is allowed for nameless URL parameters, such as image map coordinates. The right value specifies the data value of the field or parameter; this can be any expression with return type 'string', 'number' or 'float'.

The expression may use global constants, variables and random variables, BDL functions or external functions.

The list of form fields may be empty, resulting in an empty form. However, if you need an empty form, you can use the predefined empty form called FORM_NULL from the kernel.bdh include file.

Syntax

FormsSection     = { FormsDeclaration }.

FormsDeclaration = ident [ Attr ] ":"
                   [ FormItem { "," FormItem } ] ";".

FormItem         = FormItemName ":="
                   FormItemValue [ Attr ].

FormItemName     = FormExpression.

FormItemValue    = FormExpression.

FormExpression   = numeric expression | string expression

Attr             = "<" ( numeric expressionident ) ">".

Attributes

The optional attributes of a form or a form field must evaluate to a number value. While the compiler accepts any value, only those described herein have an effect. These values are named constants, defined in the kernel.bdh include file. Sometimes it makes sense to combine two or more attribute values using the bitwise-or operator '|'.

There are two groups of attributes: Usage attributes (only applicable for form fields in forms that are used context-full) and encoding attributes. Named constants for attributes are defined in the kernel.bdh include file.

Usage attributes:

Usage attributes specify how the form value in the script is combined with the value from the HTML form on a context-full form submission (WebPageSubmit function). If none of the usage attributes is specified, USE_SCRIPT_VAL is the default. This guarantees backward compatibility for scripts generated with older versions of Silk Performer. Usage attributes are mutually exclusive, meaning it makes no sense to combine two or more of them.

USE_SCRIPT_VAL (default): Specifies that the value given in the script must be used.
USE_HTML_VAL: Specifies that the value given in the form definition in the HTML form must be used. This is especially useful to make Silk Performer handle session IDs in (hidden) form fields automatically. You can still specify a form field value in the script, but this value is not used.
SUPPRESS: Specifies that a form field with the given name must not be submitted, even if the HTML form definition contains such a field. This allows using HTML forms for a WebPageSubmit function call even when the HTML form is not exactly identical to the form that should be submitted, and thus taking advantage of the attribute USE_HTML_VAL for other form fields. This is useful for modeling form submission that are done by client-side JavaScript, and form fields that are removed from a form prior to submitting it. Any field value specified in the script is not used.

Encoding attributes:

Encoding attributes specify how the unsafe characters in a field name or field value must be encoded. This is important to accommodate different encoding strategies used by different browsers in different situations.

Encoding attributes are mutually exclusive. It does not make sense to specify more than one for one form field.

ENCODE_FORM (default): This is the default and is used when none of the encoding attributes is specified. ENCODE_FORM encodes unsafe characters according to the mime type "application/x-www-form-urlencoded', see also RFC 1866, chapter 8.2.1. All popular browsers use this encoding for form submissions.
ENCODE_ESCAPE: This encodes unsafe characters according to the JavaScript function escape. The main difference to ENCODE_FORM is that blanks are encoded with "%20" instead of "+".
ENCODE_BLANKS: This encodes blanks to "%20". No other characters are encoded. Most browsers do this when a link is clicked.
ENCODE_NONE: No characters are encoded. This may be useful to accurately simulate applications where client-side Javascript performs HTTP requests without conforming to established standards.
ENCODE_CUSTOM: This is a configurable encoding type for special purposes. Use the WebFormDefineEncodeCustom function to specify how this encoding type encodes individual characters.
ENCODE_URICOMPONENT: This encodes unsafe characters according to the Microsoft JScript function encodeURIComponent. See http://msdn.microsoft.com/en-us/library/ie/aeh9cef7%28v=vs.94%29.aspx.

Attribute of a form vs. attribute of a form field

The encoding attribute of a form (as a whole) specifies the default-encoding attribute for form fields that have no encoding attribute on their own.

For example, if all form fields should use the attribute ENCODE_ESCAPE, you can specify this attribute after the form name. This encoding attribute is then used for all form fields. You can still override the encoding attribute for individual form fields by specifying another attribute for some fields.

Example

dclform
  CGI_CUST_SUPPORT:
    "email"         := "support@company.com",
    "platform"      := "Windows NT";
  AD_SERVER_PARAMS <ENCODE_NONE>:
    "~userpref"     := "12|34|56",
    "~requesttime"  := "01/01/2002";
  FORM_REDIR_LOGIN <ENCODE_NONE> :
    "~language"     := "EN",
    "~logingroup"   := "GUEST",
    "~transaction"  := "TEST",
    "~exitUrl"      := "http://www.myserver.com/
goodbye.html";
  SHOPIT_KINDOFPAYMENT:
    "choice"        := "Cash",
    "price"         := ""5.90 <USE_HTML_VAL> ,
    "paymentButton" := "" <USE_HTML_VAL> ;
  CGI_BIN_001:
    "BV_SessionID"  := "" <USE_HTML_VAL>,
    "BV_EngineID"   := "" <USE_HTML_VAL>,
    "TargetOID"     := "" <USE_HTML_VAL>;
  LOGIN_FORM_001:
    "username"      := "testuser" + string(GetUserId()),
    "password"      := "testpassword",
    "hash" := "" <USE_HTML_VAL_ENCODE_NONE>,
    "platform"      := "OS: Win2000, Browser: IE5.5,
Timezone: GMT-0300" <ENCODE_NONE>;