Designing DataWindow objects for the Web DataWindow

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

Use default properties of DataWindow column edit styles The properties of DataWindow column edit styles default to
values that optimize their appearance—for example, radio
buttons are left aligned. If you must change these style properties,
the appearance of a column in the Web DataWindow might differ from
its appearance in the DataWindow painter because the browser manages
the rendering of HTML controls. You can adjust the appearance of
the Web DataWindow by repositioning the control or resizing the
column.

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

DataWindow feature	Supported and unsupported features
Presentation styles	All presentation styles except Graph, OLE, or RichText are supported. The Composite presentation style is supported in XHTML format only. Unsupported presentation styles retrieve data but display nothing.
Nested reports	Supported in the XHTML format only.
Controls	Supported controls: Column, Computed Field, Text, Picture, Button. These controls are ignored: Graph, OLE Object, OLE Database Blob, Report, Line, Rectangle, RoundRectangle, Oval, GroupBox. 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 “
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 by using 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. Multiple columns are not supported. The dddw.lines property is not supported in Web pages because the browser controls how the DropDownDataWindow displays.
Display formats	Supported, including the use of color.
Validation rules	The expression might 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.
Properties	The following properties are not supported: EditMask.Spin DataWindow object property Sparse (Suppress Repeating Values) DataWindow object property RightToLeft DataWindow control property The Limit property is not supported in multiline edit columns in a Web DataWindow. In JavaScript, the multiline edit column maps to a textarea object, and the limit property maps to a maxlength attribute. The textarea object does not support the maxlength attribute.
Tab order	Supported in HTML 4 browsers.

Web DataWindow properties

This section describes the XML, XHTML, and HTML DataWindow
object properties for the Web DataWindow. You can set these properties
in the DataWindow painter or in script.

For more detailed information about each property, see the DataWindow Reference
or
the online Help for the property name. For information about how to
set properties in the DataWindow painter, including shared HTML
and XHTML properties, see “Setting Web generation properties
for the Web DataWindow”.

XML and XHTML
data
properties

Table 6-3 shows
row data properties for the XML and XHTML Web DataWindow.

Table 6-3: Row properties for the XML and
XHTML Web DataWindow

Property	User interface fields	Description
Data.XHTML	Read only, so no user interface field	A string containing the row data content of the DataWindow object in XHTML format
Data.XMLWeb	Read only, so no user interface field	A string containing browser-specific JavaScript that performs the XSLT transformation on the browser

XML Web DataWindow generation properties

Table 6-4 lists
properties supporting XML Web DataWindow generation.

Table 6-4: Properties supporting XML Web
DataWindow generation

Property	User interface fields	Allows you to
CSSGen.property	Web Generation property page with CSS selected as the format to configure: resource base and publish path	Specify the physical path to which a generated CSS style sheet is published and the URL indicating the location of the style sheet where the property variable is PublishPath or ResourceBase
JSGen.property	JavaScript Generation property page with XHTML selected as the format to configure: resource base and publish path	Specify the physical path to which generated JavaScript (that is included in the final XHTML page) is published and the URL indicating the location of the generated JavaScript where the property variable is PublishPath or ResourceBase
XMLGen.property	Web Generation property page with XML selected as the format to configure: resource base and publish path	Specify the physical path to which XML is published and the URL referenced by the JavaScript that transforms the XML to XHTML where the property variable is PublishPath or ResourceBase
XSLTGen.property	Web Generation property page with XSLT selected as the format to configure: resource base and publish path	Specify the physical path to which the generated XSLT style sheet is published and the URL referenced by the JavaScript that transforms the XML to XHTML (using the generated XSLT stylesheet) where the property variable is PublishPath or ResourceBase
XHTMLGen.Browser	Web Generation property page with XHTML selected as the format to configure: browser	Identify the browser in which XHTML generated within an XSLT style sheet is displayed

About PublishPath and ResourceBase PublishPath is a string that specifies the physical path of
the Web site folder to which PowerBuilder publishes generated CSS,
JavaScript, XML, or XSLT. ResourceBase is a string that specifies
the URL of the generated file.

HTML properties

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.

Some properties are now shared but property names are
unchanged In previous versions of PowerBuilder, HTML properties applied
only to the HTML Web DataWindow. Now some HTML properties are shared
with the XML Web DataWindow and the XHTML Web DataWindow. The HTML property
names have not changed.

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

Property	User interface fields	Allows you to
HTMLDW (shared)	Web 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 (HTML only)	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 (HTML only)	All fields on the Web Generation page and the JavaScript Generation page of the DataWindow object Property view. (You can also start the JavaScript Generation wizard using the Generate File 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 (shared by all Web DataWindow formats)	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.

Setting Web generation properties for the Web DataWindow

Each of the Web formats (and ultimately the files) that contribute
to the generation of a Web DataWindow require configuration:

• HTML
• XHTML
• CSS
• XML
• XSLT
• JavaScript

XHTML and HTML optimized for a browser For information about generating XHTML and HTML optimized
for a specific browser, see “Specifying Web generation
for a specific browser”

The rest of this section describes configuration of HTML,
XHTML, CSS, XML, and XSLT. For information about JavaScript configuration,
see “Using JavaScript caching
for Web DataWindow methods”.

To configure a particular Web format, you use the Web Generation
page in the DataWindow object property view. The Web Generation
page is controlled by the Format to configure drop-down
list box at the top of the view that displays the Web formats for
the Web DataWindow:

The properties that are shared by HTML and XHTML display in
the view by default. When you set shared properties, both formats
are configured at the same time:

The properties you can set are subject to change based on
the format you select:

Format to configure	Description	Properties
HTML and XHTML (shared)	Properties that are shared by both the HTML Web DataWindow and the XML Web DataWindow	Rows per page Generate JavaScript Client events Client validation Client computed fields Client formatting Client scriptable Object name Self link Self link arguments Encode self link arguments TabIndex base
HTML	HTML-only Web DataWindow properties	Browser HTML version
XHTML	XHTML-only XML Web DataWindow properties	Browser
CSS	XML Web DataWindow CSS properties	Resource base Publish path Session specific file names
XML	XML Web DataWindow data and presentation properties	Resource base Publish path
XSLT	XML Web DataWindow XSLT properties	Resource base Publish path

Typically you share style (CSS), layout (XSLT), and control
definitions (JS) for use by all clients; however, if you use dynamic
DataWindows customized for specific clients, you can force generation
of the DataWindow presentation-related document names to
be specific to each client. You do this by selecting the Session
Specific CSS, XSLT and JS Filenames check box or by setting the
CSSGen.SessionSpecific property to “yes”. This
eliminates the possibility of server-side contention for presentation
formats when the DataWindow generation is specific to the client.

For different DataWindows with the same name in the same application,
you can eliminate the possibility of server-side contention for
presentation formats and data content by entering a fully qualified
file name (rather than a path) for the publish path properties of
those DataWindows. If you do use a file name for a publish path
property, the file extension must correspond to the type of format you
are configuring. For example, if you are adding a file name to the
publish path of the XML format, the file extension must be XML.

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 Web Generation
property page in the DataWindow painter or in a script. For more
information, see “Controlling what is generated “.

You can also cache client-side methods in JavaScript 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
JavaScript 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 JavaScript caching for Web DataWindow methods

You can
use the Web Data Window JavaScript Generator wizard to create JavaScript
files (at design time) that contain the JavaScript client-side methods. You
can start the Web Data Window JavaScript Generator wizard by clicking the
Generate File button in the JavaScript Generation property page
of the DataWindow property view or from the Tool tab of the New
dialog box.

Shared JavaScript generation properties

These JavaScript files (HTML/XHTML) are shared by
all Web formats of the Web DataWindow—XML, XHTML, and HTML.

Each pass of the wizard generates only one file—which
allows you to combine or separate classes of functions. Once you
have generated one or more JavaScript files, you can attach them
to a DataWindow object using the Filename drop-down lists (for Common
Class, Date Time Management, Number Format, String Format, and User
Class) in the JavaScript Generation property page.

Generating and associating JavaScript files with a DataWindow
object enables the JavaScript functions to be cached and then reused
each time the page containing the DataWindow object displays in
the browser.

XML and XHTML JavaScript generation properties

To configure the JavaScript generation properties that are
only for the XML Web DataWindow and XHTML Web DataWindow, you select
XHTML and provide the resource base and the publish path:

Improving server-side and client-side performance

When you set new DataWindow properties to reference included
JavaScript 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 JavaScript 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 JavaScript 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 JavaScript 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 JavaScript 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 methods to include in each
JavaScript 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 JavaScript 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):

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 JavaScript
file to MyMethods.JS:

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

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 HTML Web DataWindow”.

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
might 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

For static HTML pages

If a data source for your Web DataWindow uses foreign characters
with accent marks, you might need to change the character set for
the generated Web 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:

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.

For JSP pages

For JSP pages, you assign the character set for the response
object in a page directive:

For the JSP request object, you must assign the character
set in a server-side setCharacterEncoding call:

Providing links for data

You can set properties that apply to all Web DataWindow formats
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 HTML Web DataWindow

For HTML Web DataWindow only This section applies to the HTML Web DataWindow only. XML
Web DataWindow and XHTML Web DataWindow features supersede the need
to perform any of the following actions.

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-7: Effect of ValueIsHTML property on rendered text

ValueIsHTML	Generated HTML source	Output in browser
TRUE	<I>Name</I>	Name
FALSE	&lt;I&gt;Name&lt;/I&gt;	<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 might 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
might 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-8: 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 or XHTML 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 Web 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
Web 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 SybaseSharedPowerBuilder directory.

To make the images available to the Web 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 or XHTML 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 Web page in the
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:

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 Web files of the application,
not the PBL containing the DataWindow objects.

Specifying Web generation for a specific browser

About browsers and HTML version

The Web DataWindow can generate XHTML and HTML optimized for different
browsers. You can use the Browser choice for the XHTML and HTML
formats on the Web 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 Web 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
Web 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 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.

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:

1. On the General property page of the DataWindow
   property sheet, check Web DataWindow.

   If you do not check Web DataWindow, the preview displays the
   data as an HTML table without buttons, validation rules, or other
   scripts.

2. On the Web 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.

3. Specify a value for Browser and one for Version
   if you want to preview the DataWindow for a specific client configuration.

4. Select Design>HTML Preview from the menu
   bar.

   If the menu item is disabled, open the Preview view to enable
   it.

5. Enter data and see whether validation rules behave
   as expected.

6. Use your buttons to navigate to other pages.

---