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
| Category | What is supported |
|---|---|
| Presentation styles | All except Graph, RichText, OLE, CompositeUnsupported presentation styles retrieve data but display nothing |
| Nested reports | Not supported |
| Controls | Supported controls: Column, Computed Field, Text, Picture, ButtonFor information on:
These controls are ignored: Graph, OLE Object, OLE Database Blob, |
| Retrieving data | Up to 16 retrieval argumentsFiltering and sorting are supported by setting properties with the Modify method or calling methods on the server componentSorting can also be specified via a client control methodUser-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 dropdown DataWindow must be in the same PBL as the DataWindow in which it is used. Data for dropdown DataWindows is retrieved on the server and the values for the display column are converted to HTML Select listboxes |
| Display formats | Supported, including the use of color |
| Validation rules | The expression may be evaluated on the client or the server, depending on the expressionFor information, see “Using expressions” |
| Property expressions | Evaluated on the server |
| Properties | Properties that specify autosizing of height and width or allow the user to resize or move controls are ignoredThe Sparse (Suppress Repeating Values) DataWindow object property and the RightToLeft DataWindow control property are not supported |
| Tab order | Not supported in Netscape 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:
| Property | User interface fields | Allows you to |
|---|---|---|
| HTMLDW | HTML DataWindow checkbox on the General page of the DataWindow object Property view. Selecting this checkbox 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 PowerDynamo page 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:
|
1 |
<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:
| 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:
| DataWindow control | Generated event handler names |
|---|---|
| Edit, EditMask, Dropdown Listbox, 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 |
| 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 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 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:
|
1 |
dwMine.Modify("DataWindow.HTMLGen.ResourceBase= |
|
1 |
'C:SybaseMyAppImages'") |
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 checkbox 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:
| 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 dropdown 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):
|
1 |
ids_datastore.Modify &<br /> ("DataWindow.HTMLGen.ResourceBase=" +&<br /> "'http://www.myserver.com/JavaScripts'")<br /> <br /> ids_datastore.Modify &<br /> ("DataWindow.HTMLGen.CommonJSFile=" +&<br /> "'dwcomn.js'")<br /> <br /> ids_datastore.Modify &<br /> ("DataWindow.HTMLGen.DateJSFile=" +&<br /> "'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:
|
1 |
ids_datastore.Modify &<br /> ("DataWindow.HTMLGen.UserJSFile=" +&<br /> "'http://my_server.com/JavaScripts/MyMethods.JS'") |
This example will be rendered in the generated HTML page as:
|
1 |
<SCRIPT LANGUAGE="JavaScript" SRC=<br /> "http://my_server.com/JavaScripts/MyMethods.JS"><br /> </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.