DataWindow Programmer's Guide

Home

DataWindow Programmer's Guide

Chapter 6: Using the Web DataWindow

Designing DataWindow objects

The Web DataWindow supports most PowerBuilder DataWindow functionality. This section describes what features to use to take full advantage of the Web DataWindow.

Using existing DataWindow objects

Many existing DataWindow objects work in the Web DataWindow. If a DataWindow object uses features that the Web DataWindow does not support, then the features are ignored. You can still use the DataWindow object if the remaining functionality is acceptable for your application. For example: if the DataWindow includes a graph control, the graph is ignored; if the DataWindow uses the Graph presentation style, the DataWindow object will not be useful.

Supported and unsupported features

Table 6-2: Supported and unsupported DataWindow features in the Web DataWindow

Category	What is supported
Presentation styles	All except Graph, RichText, OLE, Composite. Unsupported presentation styles retrieve data but display nothing.
Nested reports	Not supported
Controls	Supported controls: Column, Computed Field, Text, Picture, Button. For information on: expressions for Computed Fields, see "Using expressions" images for Picture controls, see "Using Picture controls" including valid HTML in a control, see "Including HTML in a control" Button controls and supported actions, see "Using Button controls " These controls are ignored: Graph, OLE Object, OLE Database Blob, Report, Line, Rectangle, RoundRectangle, Oval, GroupBox.
Retrieving data	Up to 16 retrieval arguments. Filtering and sorting are supported by setting properties with the Modify method or calling methods on the server component. Sorting can also be specified via a client control method. User-specified queries using the QueryMode property are not supported.
Updating data	Same as PowerBuilder DataWindow control. The DataWindow object must contain editable columns.
Edit styles	All edit styles are supported except EditMask. If the DataWindow uses the EditMask edit style, the styles specified are treated as though they were specified as a display format.
DropDown DataWindows	A drop-down DataWindow must be in the same PBL as the DataWindow in which it is used. Data for drop-down DataWindows is retrieved on the server and the values for the display column are converted to HTML Select list boxes.
Display formats	Supported, including the use of color.
Validation rules	The expression may be evaluated on the client or the server, depending on the expression. For information, see "Using expressions"
Property expressions	Evaluated on the server.
Layout	Properties that specify autosizing of height and width or allow the user to resize or move controls are ignored.
Tab order	Supported in HTML 4 browsers.

Setting HTML properties in the DataWindow painter

There are four types of HTML properties you can set in the DataWindow painter. The first three apply to the DataWindow object itself. The last applies to bitmap, column, computed field, and text controls in the DataWindow object. All these properties can also be set in a script.

For more information about each property, see the DataWindow Reference or the online Help for the property name shown in the left column:

Table 6-3: HTML properties you can set in the DataWindow painter

Property	User interface fields	Allows you to
HTMLDW	HTML DataWindow check box on the General page of the DataWindow object Property view. Selecting this check box sets this property to Yes.	View the HTML in a browser using Design>HTML Preview (or if you plan to use the DataWindow object with a custom Web DataWindow server component). The generic server component automatically sets this property to Yes.
HTMLTable.property	All fields on the HTML Table page of the DataWindow object Property view.	Change the display characteristics of HTML tables, including border style and cell width and padding.
HTMLGen.property	All fields on the HTML Generation page and the JavaScript Generation page of the DataWindow object Property view (You can also start the JavaScript Generation wizard from a button on the JavaScript Generation page).	Control the number of rows displayed on the page, generate HTML for a specific browser or HTML version, choose client-side features to incorporate into the page, and set up JavaScript caching to enhance performance.
HTML.property	All fields on the HTML page of the Property view for a Column, Computed Field, Text, or Picture control in a DataWindow object.	Set up hyperlinks and retrieval arguments typically used to create master/detail Web pages, specify whether the content of a control should be rendered as HTML, and specify any HTML to be appended to a control.

Controlling the size of generated code

Some supported features increase the size of the generated code. If you do not use a feature such as display formatting, validation rules, or client-side scripting, you can enhance performance by preventing the server component from generating code for the unused feature. You can turn these features on or off on the HTML Generation property page in the DataWindow painter or in a script. For more information, see "Controlling what HTML is generated ".

You can also cache client-side methods in JavaScript (JS) files to reduce the size of the generated code and increase performance on both the server and the client. Without JavaScript caching, each time a Web DataWindow is rendered in a client browser, JavaScript code for DataWindow methods is generated on the server and downloaded to the client. When you set DataWindow properties to reference cached JS files, the methods defined in the files are not generated with the HTML in any Web DataWindow pages that are sent to the page server (and client browser).

For more information, see "Using JavaScript caching for Web DataWindow methods".

Using expressions

In general, expressions for validation rules and computed fields are translated into JavaScript and evaluated in the client browser. For validation of data entry, the user gets immediate feedback on the new data.

Some expressions have to be evaluated on the server. This may be because the evaluation involves all the rows, rather than data on the current page only, or because the expression does not translate into JavaScript.

If an expression includes these functions, it will be evaluated on the server:

Aggregation functions, like Sum, Max, Average, First
Case function
External functions

If you use an aggregation function in a computed field, the value is computed on the server and displayed on the client. If the user edits data, the value is not updated. If an action occurs that reloads the page, the value is computed again based on the changed data.

ProfileInt and ProfileString return default values

The ProfileInt and ProfileString DataWindow expression functions do not examine a user's INI files if you use them in an expression evaluated on the client. Doing so would be a security violation. They always return the default value.

Using foreign language character sets

If a data source for your Web DataWindow uses foreign characters with accent marks, you may need to change the character set for the generated HTML page to display the characters properly. This is also necessary if you expect to update the data with foreign character text. You can use the HTML editor to edit the <META> tags in the <HEAD> section of the generated page. The following example uses the utf8 character set instead of the default iso-8859-1 character set:

<META content="text/html; charset=utf-8" http-equiv="Content-Type">

Changing the character set in EAServer

You can also change the character set used by your component in EAServer by setting the com.sybase.jaguar.component.code.set property for the component. By default, the component uses the server's codeset.

Providing links for data

You can set properties that cause columns, text, computed fields, and Picture controls to be hyperlinks. In the painter, select the control and choose the HTML tab in the Properties view. The URL you specify must be valid when you deploy your application.

Rather than set link information in the painter, you can set the HTML properties for columns by calling methods of the server component. For information, see the SetColumnLink method in the DataWindow Reference.

Rendering HTML for controls in a Web DataWindow

Including HTML in a control

You can include valid HTML in some controls in a DataWindow object, including a text control, column, or computed field. To render the contents of the control as HTML when the HTML for the DataWindow is generated, set the control's ValueIsHTML property to TRUE. For example, suppose a text control's text property is <I>Name</I>. The following table shows how the text is rendered in the generated HTML and displayed in a browser.

Table 6-4: Effect of ValueIsHTML property on rendered text

ValueIsHTML	Generated HTML source	Output in browser
TRUE	<I>Name</I>	Name
FALSE	<I>Name</I>	<I>Name</I>

No validation

The HTML generator does not validate the HTML you include in controls in DataWindow objects. If the HTML is not valid, the DataWindow may not display correctly.

Appending HTML to a control

The AppendedHTML property enables you to append your own HTML to the HTML generated by the HTML generator component. You can use this feature to specify attributes and event actions. The HTML you specify for the AppendedHTML property value is appended to generated syntax for the rendering of a DataWindow control before the closing bracket of the HTML element for that control.

No validation

The HTML generator does not validate the HTML you append to controls in DataWindow objects. If the HTML is not valid, the DataWindow may not display correctly.

You must also make sure not to use an event handler name that is already generated for a DataWindow control as a client-side event handler. These include:

Table 6-5: Generated event handler names

DataWindow control	Generated event handler names
Edit, EditMask, DropDownListBox, or DropDownDataWindow	onFocus, onClick, onChange, and onBlur
CheckBox or RadioButton	onFocus, onClick, and onBlur
TextBox, Picture with link, or Button	onClick

Using Button and Picture controls

Using Button controls

When a DataWindow object includes a Button control, the button becomes an HTML button element in the Form element for the Web DataWindow client control. The button action becomes JavaScript code for the button's Clicked event. You do not need to write any code yourself.

You can use Button controls for:

Navigation
Buttons with the PageFirst, PageLast, PageNext, and PagePrior actions let the user scroll to other rows in the result set.
Getting and editing data
Buttons with Retrieve, Update, InsertRow, DeleteRow, and AppendRow actions let the user maintain data. There must be updatable columns in the DataWindow object.

These button actions are not supported and are ignored:

Cancel	QueryClear
Filter	QueryMode
Preview	QuerySort
PreviewWithRulers	SaveRowsAs
Print	Sort

Setting SelfLink properties to enable navigation buttons

Button actions send information back to the server, whose scripts apply the action to the DataWindow data. Then the HTML page is reloaded. To complete this loop, you must set the SelfLink property for the DataWindow object so that the server knows what page to reload.

You can set this property in the DataWindow painter on the HTML Generation tab in the DataWindow properties view, or you can set it in a server-side script. The value is the name of the application server template or file to be reloaded--generally, the name of the current document. If the DataWindow uses retrieval arguments, they must be provided in the SelfLinkArgs property.

For more information, see "Passing page-specific data to the reloaded page" and the SetSelfLink method in the DataWindow Reference. For information on setting links on a DataWindow object (such as a button or column) in the PowerBuilder HTML editor, see the chapter on the Web DataWindow DTC in Working with Web and JSP Targets.

GIF and JPEG images for buttons

The picture on a button in a DataWindow object can be rendered in the Web browser as a JPEG, GIF, or BMP image. Use a JPEG or GIF image to ensure that the image will display on all browsers. PowerBuilder provides GIF images for commonly used buttons such as Retrieve, Update, PageNext, and so on. These pictures are included in the DWACTION.JAR file in the Sybase\Shared\PowerBuilder directory.

To make the images available to the HTML page in the Web browser, you must uncompress the JAR file, deploy the image files to the page server, and set the HTMLGen.ResourceBase property to the directory where the files are located.

Alternative to buttons: use methods of the client control

If you want to use an existing DataWindow object that does not have Button controls, you can edit the DataWindow object and save a new version with Button controls. However, if you are sharing DataWindow objects with an existing application and it is not practical to edit them, your Web page can include HTML buttons that call methods of the Web DataWindow client control.

There are methods of the client control that correspond to each of the supported button actions. For information, see "Writing client-side scripts".

Using Picture controls

You can use any image types the browser supports, most commonly JPEG or GIF. Use relative paths for ease of deployment.

To make sure the images are available to the HTML page in the Web browser, place the image files in a directory on the Web server and then set the HTMLGen.ResourceBase property to that directory. You can do this in the DataWindow painter on the JavaScript Generation page of the DataWindow property view, or in a script:

dwMine.Modify("DataWindow.HTMLGen.ResourceBase=

        'C:\Sybase\MyApp\Images'")

The ResourceBase property also specifies the location of JavaScript include files. See "Using JavaScript caching for Web DataWindow methods".

Where to deploy image files

The image files need to be deployed to the Web server, not the component server. If these servers are on different computers, the files belong with the templates and HTML files of the application, not the PBL containing the DataWindow objects.

Specifying HTML generation for a specific browser

About browsers and HTML version

The Web DataWindow can generate HTML optimized for different browsers. You can use the Browser choice on the HTML Generation tab of the DataWindow property sheet to preview what the DataWindow looks like in different browsers. You can also specify an HTML version that the HTML generation should use if it does not recognize the browser.

At runtime, a server-side script should find out what browser the current client is using and pass that information to the server component. For information, see "SetBrowser " and the SetBrowser method in the DataWindow Reference or online Help.

Using absolute positioning in Netscape

Netscape implements absolute positioning differently than Internet Explorer. To format the DataWindow with absolute positioning for Netscape browsers, you must set the DataWindow HTMLGen.NetscapeLayers property to TRUE. You can do this in the DataWindow painter by selecting the Use Layers for Netscape check box on the HTML Generation page of the DataWindow property view. Alternatively, you can use a DataWindow Modify call in the script for the Generate method of the HTML Generator (nv_remote_datawindow in PBDWRMT.PBL that ships with PowerBuilder).

The default DataWindow HTML generator generates code for determining the browser type and version of the client browser. For Netscape browsers earlier than the 4.0 version, the DataWindow is formatted as an HTML table, whether or not the NetscapeLayers property is set.

Limitations in Netscape

Certain functionality in a Netscape browser using absolute positioning may 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.

Using JavaScript caching for Web DataWindow methods

You can use the Web DataWindow JavaScript Generator wizard to create JS files (at design time) that contain all the Web DataWindow JavaScript client-side methods. You can start the wizard from the Tool tab of the New dialog box, or from the JavaScript Generation page of the DataWindow property view in the DataWindow painter.

Improving server-side and client-side performance

When you set new DataWindow properties to reference included JS files, the methods defined in the referenced files are not generated with the HTML in any Web DataWindow pages that are sent to the page server and client browser. Using JS files also reduces the size of the HTML page rendered in the browser.

With JavaScript caching, you improve performance on the client machine as long as the client browser 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 client-side 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.

Web DataWindow JavaScript Generator wizard

With the Web DataWindow JavaScript Generator wizard, you can generate only one JS file at a time. The wizard gives you the option of including all Web DataWindow methods in a single file, but you can also restrict the types of method to include in each JS file it generates every time you use the wizard. The different method types correspond to the following DataWindow HTML properties:

Table 6-6: Methods generated by JavaScript Generator wizard in cached files

HTMLGen.property	Contents of cached file
CommonJSFile	Methods used by all DataWindows.
DateJSFile	Methods used by DataWindows with date and time formatting.
NumberJSFile	Methods used by DataWindows with number formatting.
StringJSFile	Methods used by DataWindows with string formatting.
UserJSFile	User-defined client-side JavaScript methods--these cannot be generated by the Web DataWindow JavaScript Generator wizard (see User-defined JavaScript methods).

All of these properties are optional. You can set each of the properties from the JavaScript Generation page of the DataWindow property view, selecting the files you generate with the wizard as values. The wizard registers each file it generates, making it available for selection from the drop-down lists in the DataWindow property view.

Using the ResourceBase property

You must deploy all cached files for your Web application to your Web server. You can use relative URLs or path names for cached JS files if you specify their location in the HTMLGen.ResourceBase property. (You set these on the JavaScript Generation page of the DataWindow property view in the DataWindow painter.) The ResourceBase property is also used to specify the location of image files.

If you do not set the HTMLGen.ResourceBase property, you must include the complete URL in the values of any of the HTMLGen properties that you set. In either case, the URLs are rendered as SRC attributes inside SCRIPT tags in the pages generated by the Web DataWindow component and sent to the client browser.

Setting the properties in script

You can customize the DataWindow HTML Generator component (nv_remote_datawindow in PBDWRMT.PBL that ships with PowerBuilder), setting the HTMLGen properties in the script for the Generate method. This example sets the URL location for included files and names the files for common and date-formatted Web DataWindow methods that you deploy to the Web server (and that will be downloaded to browser clients the first time they connect to the Web site):

ids_datastore.Modify &
    ("DataWindow.HTMLGen.ResourceBase=" +&
    "'http://www.myserver.com/JavaScripts'")
ids_datastore.Modify &
    ("DataWindow.HTMLGen.CommonJSFile=" +&
    "'dwcomn.js'")

ids_datastore.Modify &
    ("DataWindow.HTMLGen.DateJSFile=" +&
    "'dwdate.js'")

User-defined JavaScript methods

You can also reference a file where you store your own client-side JavaScript methods. To use this feature, you must assign the name of the file to the DataWindow HTMLGen.UserJSFile property and make sure the file is available to your Web server. As for the wizard-generated JavaScript files, you can use the HTMLGen.ResourceBase property to set the location for the file, or you can include the complete path to the file in the property value assignment.

You can make this assignment in the DataWindow painter or in script. The following script sets the user-defined JS file to MyMethods.JS:

ids_datastore.Modify &
    ("DataWindow.HTMLGen.UserJSFile=" +&
     "'http://my_server.com/JavaScripts/MyMethods.JS'")

This example will be rendered in the generated HTML page as:

<SCRIPT LANGUAGE="JavaScript" SRC=
"http://my_server.com/JavaScripts/MyMethods.JS">
 </SCRIPT>

You can then call client-side methods stored in the MyMethods.JS file from the HTML syntax rendered for (or appended to) controls in a DataWindow object. For information on generating or appending HTML syntax to controls, see "Rendering HTML for controls in a Web DataWindow".

Previewing the DataWindow

To see what the DataWindow will look like in a Web DataWindow application, you can use HTML Preview.

To get an HTML preview of a Web DataWindow:

On the DataWindow property sheet, General page, check HTML DataWindow.
If you do not check HTML DataWindow, the preview displays the data as an HTML table without buttons, validation rules, or other scripts.
On the HTML Generation page, specify a value for Rows per Page.
This sets the PageSize property for the DataWindow object. To display only one row of data, specify 1.
Specify a value for Browser and one for Version if you want to preview the DataWindow for a specific client configuration.
Select Design>HTML Preview from the menu bar.
If the menu item is disabled, open the Preview view to enable it.
Enter data and see whether validation rules behave as expected.
Use your buttons to navigate to other pages.


	Expand Search