HTMLGen.property

Description

Settings that control the level of features incorporated into HTML generated for the DataWindow.

Applies to

DataWindow objects

Syntax

Describe and Modify argument:

"DataWindow.HTMLGen.property { = ' value ' }"

Parameter

Description

property

A property that controls how HTML is generated for a DataWindow. Properties and their values are listed in the table below.

value

The value to be assigned to the property. Value can be a quoted DataWindow expression where noted.

Property for HTMLGen

Value

Browser

(exp) A string identifying the browser in which you want to display the generated HTML. The value should match the browser identifier part of the text string that the browser specifies in the HTTP header it sends to the server. This property is usually set dynamically on the server according to the HTTP header returned from the client.

Recognized strings are listed in “Browser recognition”.

ClientComputedFields

(exp) Whether computed fields that reference column data are translated into JavaScript and computed in the client browser.

Values are:

  • Yes – (Default) Computed fields are translated to JavaScript where possible.

  • No – Computed fields are always calculated on the server.

Regardless of this setting, if the computed field includes aggregation functions, the computed field is calculated on the server. For more information about this and the following properties, see “Client properties”

ClientEvents

(exp) Whether JavaScript code to trigger events is included in the generated HTML.

Values are:

  • Yes – (Default) JavaScript for triggering events is generated.

  • No – JavaScript for events is not generated.

ClientFormatting

(exp) Whether display formats are applied to data items that do not have focus. JavaScript for formatting the data is translated from display formats specified in the DataWindow painter. If you want to use regional settings, such as a period as a date separator and a comma as a decimal separator, you must set ClientFormatting to Yes.

Values are:

  • Yes – (Default) Display formats are applied to data.

  • No – Display formats are not used.

ClientScriptable

(exp) Whether client-side JavaScript can interact with the control.

Values are:

  • Yes – Client-side JavaScript can call methods of the control.

  • No – (Default) Client-side JavaScript cannot call methods.

This option adds approximately 20K to the size of the generated HTML.

ClientValidation

(exp) Whether JavaScript code to perform validation of user-entered data is included in the generated HTML. The validation code is translated from validation expressions specified in the DataWindow painter.

Values are:

  • Yes – (Default) Validation expressions are generated.

  • No – Validation expressions are not generated.

CommonJSFile

(exp) Cache file name for common JavaScript functions required by Web DataWindows at runtime. If you set this property, the file is downloaded to the browser client once per session for use by all Web DataWindows. You can prefix the file name to a URL, or you can use the URL that you set with the HTMLGen.ResourceBase property. See “JavaScript caching”.

DateJSFile

(exp) Cache file name for common Web DataWindow functions that use a date format. If you set this property, the file is downloaded to the browser client once per session for use by all Web DataWindows. You can prefix the file name with a URL, or you can use the URL that you set with the HTMLGen.ResourceBase property. See “JavaScript caching”.

EncodeSelfLinkArgs

(exp) A switch to disable HTML 4 encoding of the evaluated HTMLGen.SelfLinkArgs expressions that are generated as hidden fields. The standard encoding limits character replacement to: ", &, <, and >. Disabling the standard encoding allows you to encode additional characters, but you must encode the argument expressions yourself.

Values are:

  • Yes – (Default) Encoding performed by PowerBuilder.

  • No – Encoding not performed.

GenerateDDDWFrames

(exp) Specifies whether drop-down DataWindows are generated using inline frames (iFrames). The use of iFrames enhances the display so that the drop-down DataWindow displays in a Web application as it would in a Windows application. Using iFrames increases the volume of markup generated.

Values are:

  • Yes – (Default) Drop-down DataWindows are generated in formatted div elements over an iFrame.

  • No – Drop-down DataWindows are generated in HTML select elements.

The use of the GenerateDDDWFrames option for drop-down DataWindows is supported only in the Internet Explorer browser. In other browsers, the HTML select element is always used.

GenerateJavaScript

(exp) Specifies whether to generate JavaScript if the browser is not recognized. Keep in mind that without JavaScript, updating of data is not available. Navigation links are still supported.

Values are:

  • Yes – (Default) JavaScript is generated even if the browser is not recognized. The resulting JavaScript is portable and does not use browser-specific features.

  • No – JavaScript is not generated unless the browser is recognized

HTMLVersion

(exp) The version of HTML to generate.

Values are:

  • 3.2 – (Default) The HTML will include style sheets, but no absolute positioning or regular expressions.

  • 4.0 – The HTML will include style sheets, absolute positioning, and regular expressions.

If the browser is recognized, this property is ignored and browser-specific HTML is generated.

NetscapeLayers

(exp) Formats the Web DataWindow for Netscape 4.0 or later using absolute positioning (in a manner similar to the formatting for Internet Explorer). See “NetscapeLayers property”.

NumberJSFile

(exp) Cache file name for common Web DataWindow functions that use a number format. If you set this property, the file is downloaded to the browser client once per session for use by all Web DataWindows. You can prefix the file name with a URL, or you can use the URL that you set with the HTMLGen.ResourceBase property. See “JavaScript caching”.

ObjectName

(exp) A string specifying a name used in generated code for the Web DataWindow client control, page parameters, and client-side events.

You must specify a unique object name when there will be more than one Web DataWindow on a Web page so that names will not conflict.

PageSize

(exp) The number of rows of data to include in a generated Web page. If the Web page does not include all available rows, you can include button controls to navigate to the rest of the data. To include all available rows in the page, specify 0 for PageSize.

If the HTMLDW property is set to Yes, PageSize is used.

If it is set to No, PageSize is ignored and all rows in the result set are generated in a single page.

PagingMethod

A value of the WebPagingMethod enumerated variable that determines how paging is handled.

Values are:

  • PostBack! (0) – (default) The control posts back to the server to perform paging operations.

  • Callback! (1) – The control calls a service on the client to perform paging operations.

  • XMLClientSide! (2) – The control retrieves the entire XML result set and performs paging operations on the client. This option is only available when the XML rendering format is used.

See “PagingMethod”.

ResourceBase

(exp) The URL for included JavaScript files. If you set this property, you do not need to include a URL in the values for these other HTMLGen properties: CommonJSFile, DateJSFile, NumberJSFile, and StringJSFile.

SelfLink

(exp) A string specifying the URL for the current page. It cannot include parameters. Parameters specified in SelfLinkArgs can be added when HTML is generated.

SelfLink is used to generate URLs for navigation buttons that obtain additional rows from the result set and for other buttons that reload the page, such as Update and Retrieve.

SelfLinkArgs

A string in the form:

argname='exp'{ | argname = 'exp' } ... 

Argname is a page parameter to be passed to the server.

Exp is a DataWindow expression whose value is a string. The DataWindow in the server component evaluates it, converts it using URL encoding, and includes it in the SelfLinkArgs string.

The evaluated SelfLinkArgs expressions are included in the generated HTML as hidden fields. The arguments supply information that the server needs to render additional pages of the result set, such as retrieval arguments.

StringJSFile

(exp) Cache file name for common Web DataWindow functions that use a string format. If you set this property, the file is downloaded to the browser client once per session for use by all Web DataWindows. You can prefix the file name with a URL, or you can use the URL that you set with the HTMLGen.ResourceBase property. See “JavaScript caching”.

TabIndexBase

(exp) Sets the starting tab order number for a Web DataWindow. This property is useful for a Web page with multiple Web DataWindows when you can tab between columns of the DataWindows. Setting this property has no effect on page functionality when the page is viewed in a browser that does not support the tab index attribute. The maximum tab index allowed for a page is 32767. See “TabIndexBase property”.

UserJSFile

(exp) Cache file name for user-defined Web DataWindow functions. If you set this property, the file is downloaded to the browser client once per session for use by all Web DataWindows. You can prefix the file name to a URL, or you can use the URL that you set with the HTMLGen.ResourceBase property. See “JavaScript caching”.

Usage

Most of these properties are considered only when the HTMLDW property is set to Yes.


Browser recognition

The Browser and HTMLVersion properties are always considered when HTML is generated, regardless of the HTMLDW setting.

Browser identification strings are sent by the client to the server in the HTTP header. The server component can assign the HTTP_USER_AGENT value from the HTTP header to the Browser property. If the string specifies a browser that the DataWindow engine supports, the DataWindow will generate HTML optimized for that browser. Browser-specific HTML is generated only for Microsoft Internet Explorer and Netscape browsers.

If the browser is not recognized or not specified, then the generated HTML will use the HTMLVersion and GenerateJavaScript properties to decide what features to include. DataWindow HTML generation recognizes these browsers:

Browser

HTTP header string

HTML features used

Netscape

Mozilla/1.x (

No style sheets, no absolute positioning, no JavaScript.

Mozilla/2.x ( Mozilla/3.x (

JavaScript.

No style sheets, no absolute positioning, no regular expressions.

Mozilla/4.x (

Style sheets, JavaScript, regular expressions.

No absolute positioning.

Microsoft Internet Explorer

Mozilla/1.22 (compatible; MSIE 2.x;

No style sheets, no absolute positioning, no tab order, no JavaScript.

Mozilla/2.0 (compatible; MSIE 3.x;

Style sheets, tab order, JavaScript.

No absolute positioning, no regular expressions.

Mozilla/4.0 (compatible; MSIE 4.x, Mozilla/4.0 (compatible; MSIE 5.x; Mozilla/4.0 (compatible; MSIE 6.x;

Style sheets, absolute positioning, tab order, regular expressions.

Opera

Mozilla/3.0 (compatible; Opera 3.x;

JavaScript, regular expressions.

No style sheets, no absolute positioning.

NoteColumns with RichText edit style To save rich text formatting in columns with the RichText edit style, the HTMLGen.Browser property must be set to "Microsoft Internet Explorer" and the HTMLGen.HTMLVersion property to "4.0".


Client properties

The ClientEvents, ClientFormatting, ClientValidation, ClientComputedFields, and ClientScriptable properties control the amount of JavaScript that is generated for the Web DataWindow, which impacts the size of the page that is downloaded to the browser. You can reduce the size of the generated HTML by setting one or more of the properties to No.


JavaScript caching

You can also reduce the size of the generated HTML by setting up cache files for common Web DataWindow client-side methods. You can generate these files using the JavaScript Generation wizard that you launch from a button on the JavaScript Generation tab of the Properties view in the DataWindow painter.

Once you generate these files, you can set the file names as values for the CommonJSFile, DateJSFile, NumberJSFile, and/or StringJSFile properties. When you set these properties, the methods defined in the referenced files will not be generated with the HTML in any Web DataWindow pages that are sent to the page server and client browser.With JavaScript caching, you improve performance after the first Web DataWindow page is generated—as long as the browser on the client computer is configured to use cached files. With caching enabled, the browser loads the JS files from the Web server into its cache, and these become available for all the Web DataWindow pages in your application. There is no performance gain if the browser does not find the JS files in its cache since, in this case, it reloads the files from the Web server.


PagingMethod

The PagingMethod property determines whether the control uses the client-side script callback mechanism introduced in the .NET Framework 2.0 to execute server-side code without posting and refreshing the current page.

The default is to post back to the server (PostBack!).

The Callback! option uses script callbacks to retrieve the next page of XML data. It corresponds to the Microsoft GridView control’s EnableSortingAndPagingCallback property, but applies only to paging. Client-side sorting is handled by another mechanism.

For the XML rendering format, the design of the Callback! option requires that a reusable XSLT stylesheet be generated so that the browser can cache it. The benefit from this requirement is that only the XML data for the next requested page need be returned by the callback. This XML data is always trivial in size (about a 1 to 20 ratio), resulting in significant bandwidth savings. This is unlike other implementations, where the entire presentation is always regenerated and downloaded again from every callback.

The generated XSLT stylesheet is not reusable, and therefore cannot be cached by the browser, if the DataWindow layout is inconsistent page-to-page, or it does not contain a complete first page of data. In these scenarios, the Callback! option defers to PostBack! until a stylesheet can be generated that is reusable, and can therefore be cached in the browser.

The XMLClientSide! option is only available with the XML rendering format. It retrieves the entire XML result set and uses XSLT re-transformation of the cached stylesheet to perform paging on the client. This option can currently be used only if the presentation style is uniform from page to page. For example, it cannot handle a summary band on the last page.

When PagingMethod is set to XMLClientSide!, InsertRow, AppendRow, and DeleteRow actions do not require a postback or callback to the server. However, computed fields in the DataWindow that are dependent on the RowCount method are not refreshed until an action such as Update or Retrieve forces a postback to the server.


NetscapeLayers property

Even if you set the NetscapeLayers property to true, certain functionality in a Netscape browser using absolute positioning might not be identical to the functionality available with Internet Explorer. For example, you cannot tab between DataWindow columns using a Netscape browser on an NT machine (although you can do this using a Netscape browser on a Solaris machine).


TabIndexBase property

If you add Web DataWindows to a page that already has a Web DataWindow on it, you can set the TabIndexBase property for each Web DataWindow you add.

For a page with two Web DataWindows, setting the tab index base for the second DataWindow to a number greater than the tab index for the last column of the first DataWindow allows the user (using an Internet Explorer browser) to tab through all the columns of the first DataWindow before tabbing to the second DataWindow. Otherwise, pressing the Tab key could cause the cursor and focus to jump from one DataWindow to another instead of tabbing to the next column in the DataWindow that initially had focus.


In the painter

Select the DataWindow object by deselecting all controls; then set the values in the Properties view, Web Generation tab or JavaScript Generation tab. Select HTML/XHTML from the Format to Configure list to display the properties.

Examples

Example 1

setting = dw1.Describe
		("DataWindow.HTMLGen.Browser")

Example 2

dw1.Modify("DataWindow.HTMLGen.ClientValidation = 'no'")

Example 3

dw1.Modify("DataWindow.HTMLGen.PublishPath=
   'C:\Inetpub\wwwroot\MyWebApp\generatedfiles'")
dw1.Modify("DataWindow.HTMLGen.ResourceBase=
   '/MyWebApp/generatedfiles'")

Example 4

This statement sets the XMLGen.Paging property so that the complete result set is downloaded to the client and paging takes place on the client:

dw1.Modify("DataWindow.HTMLGen.PagingMethod=XMLClientSide!")