In my January article in PBDJ (Vol. 7, issue 1) I covered the basics of the Web DataWindow and we ended the article with the home page. We'll now move on to the employee page.

The Employee Page
The employee page is going to use two DataWindows: one that displays some department details, another that displays a simple list of employees for a given department. For the department detail DataWin-dow create a tabular DataWindow that retrieves the dept_id, dept_name and dept_head_id from the department table. Specify a retrieval argument for dept_id and use that in the where clause (try department 100 when retrieving). Zero out the tab order for all columns so they are uneditable. Save the DataWindow as "d_department_detail".

For the employee DataWindow create a grid DataWindow that queries the employee table and retrieves the emp_id, emp_fname, emp_lname and phone columns. Add a dept_id retrieval argument for this query as well. Make sure to zero out the tab order for the emp_id column so it won't be editable. Add a button to the summary band with the action set to update. Pretty up the DataWindow as much as you want, and then save it as "d_employees".

Now back to PowerSite and the Sybase HTML DataWindow DTC. DTC stands for design-time control. What are design-time controls? Like normal controls, these allow you to set properties and call methods. But unlike normal controls, design-time controls aren't usually WYSIWYG. The Sybase HTML DataWindow DTC appears at design time like a white box, but at runtime (that is, in the browser) it appears very much as it would in a DataWindow control. In the Maui release of the Web DataWindow the DTC will actually appear at design time as a preview of what it will look like in the browser.

Two details are worth noting about this page. First, we'll be placing two Web DataWindows on the same page. Second, our employee Web DataWindow will be updatable.

In PowerSite right-click "Dw-dtc" in the project view and select "New." On the "Files" tab of the "New" dialog select "Blank HTML Page" and click OK. Name the page "Employees" and accept all other defaults. You should then see the "Page" tab, editing "Employees.htm."

Select "Insert | Components | ActiveX" in the menu (or click on the ActiveX toolbar button), and you should see the "Insert ActiveX Control" dialog. Select "Sybase HTML DataWindow DTC" and click OK. (Be careful not to select the "Sybase DataWindow DTC" - that's included only for backward compatibility.) You should then see the "General" tab of the "Sybase HTML DataWindow DTC Properties" dialog. One important rule for those who aren't yet familiar with this dialog: always be sure to visit every tab in the dialog to make sure you've set all the correct options. If you miss even a minor setting, you probably won't get a meaningful error message when you try to view your Web DataWindow in the browser. Sometimes you'll see nothing at all, just a blank page.

There's not much to the General tab. You can load the source for a DataWindow object from a DataWindow export file (an .SRD file), a PBL or a PSR file. Typically, you'd choose a PBL. In this case select the PBL in which you stored the department DataWindow, and select "d_department_detail" from the "DataWindow" drop-down. Check the "Generate absolute path in script" checkbox, which will include the full path of your PBL in the generated JavaScript. You'd never check this option in a real production setting (unless you develop in PowerSite and PowerBuilder right on your Jaguar server machine!); rather, you'd deploy the PBL to a directory that's in the system path on the remote server where Jaguar is running. (You can also deploy to the "...Jaguar CTS\bin" directory). Finally, there's the "Edit DataWindow" button, which launches the DataWindow Builder. I never click that button because I've never installed the DataWindow Builder - I already have PowerBuilder!

Let's move to the "Control" tab. There's only one required option here, and that's the "Connection." Choose the "EAS Demo DB V3" database connection that you defined above (it may default to that connection already). But because we'll have two HTML DataWindows on the same page, we'll need to set one of the lesser-used options: the control name. Check the "Override" box next to the name, then name the control "htmlDW_dept". The other options take some time to explain, so I'll cover them later.

The "Retrieval Arguments" tab lists all of the retrieval arguments for the specified DataWindow. In this case you should see the "dept_id" retrieval argument that you defined when building the DataWindow. The remaining options should already be populated with a "Value Type" of "Page Parameter" and "Values" of "dept_id". Those options mean that our employee page is going to expect a page parameter named "dept_id" and our Web DataWindow is going to use that page parameter to retrieve. Just like magic!

We have no need to use the "Link To" tab for the employee page because this page doesn't contain any hyperlinks. We'll use this tab later when we create the department page.

The "Page Parameters" tab displays the list of parameters that this page requires. Back on the "Retrieval Arguments" tab we already saw that this page expects a parameter of "dept_id". When we selected the department detail DataWindow, the HTML DataWindow DTC added the "dept_id" parameter to this tab. You need to change settings on this tab only if you plan to insert, update or delete data for this Web DataWindow. In this case we're not updating the department detail, so we'll leave the tab as is. But what does that wording at the top of the tab mean? "Self Link"?

"Self Link," a common technique employed with dynamically generated Web pages, is used by the page to regenerate its contents. When a Web DataWindow updates its data, it posts a request to its own URL, passing page parameters (as specified on the "Page Parameters" tab) as well as parameters specifying what to do, such as "update." The Web DataWindow knows how to act on all of these parameters to update the data, and it then generates new HTML for the return trip to the browser. So this is called a "self link" because the page links to itself. We'll use this for the employee Web DataWindow.

Finally, we come to the "Jaguar" tab. (Now would be a good time to start Jaguar if you haven't already.) Figure 1 (reproduced here from my previous article) shows that the HTML Generator component in Jaguar is used when building Web DataWindows. So the HTML DataWindow DTC needs to know how to get to Jaguar and the HTML Generator component. First, check the "Enable Jaguar Component" box. If you don't see any Jaguar servers listed, click the "Jaguar Servers" button and type in the information to get to your Jaguar server (e.g., Server Name = localhost, Port = 9000, Login Name = jagadmin, and no Password). Back on the Jaguar tab, expand the Jaguar tree and select "HTMLGenerator." Then the important step: be sure to click the "Set" button. This will set the Jaguar information in the "Selected Server" and "Selected Component" text above the tree. Your property sheet should look like Figure 2.

We're finally done with the Sybase HTML DataWindow DTC Properties dialog, so click OK. You probably think it's now time to write all the JavaScript to make our Web DataWindow work. No. That's the beauty of the HTML DataWindow DTC - it does all the work for you. You can call methods against the DTC, but that's not required to make the Web DataWindow work.

We're not quite done with this page yet. We still have to add the employee DataWindow.

Hit enter to add a line between the two Web DataWindows, then click the ActiveX button to add the second HTML DataWindow DTC. Use the chart in Table 1 to fill in the property sheet.

This is the first time we've used the "Page Parameters" tab. Setting the "dept_id" column as a "Passed Parameter" means that whenever the page executes a Self Link it will pass the department ID as a page parameter. In this case, when the user changes some data and clicks the update button, the page will pass the current department ID to itself on the server so that it can reretrieve the data, make the appropriate changes to it, update the changes and then regenerate the page to display the new data. The beauty of it all is that you don't have to write any code.

We're finally done, so just close the page and save your changes.

The Department Page
The department page is going to display a simple list of department names using a DataWindow. Create a tabular DataWindow that queries the department table and retrieves the dept_id and dept_name columns, but displays only the department name. Make sure to zero out the tab order for the department name (otherwise the department name would render in HTML as an editable control and we wouldn't be able to use it as a hyperlink). Save the DataWindow as "d_departments".

In PowerSite right-click "Dw-dtc" in the project view and select "New". On the "Files" tab of the "New" dialog select "Blank HTML Page" and click OK. Name the page "Departments" and accept all other defaults. You should then see the "Page" tab, editing "Departments.htm".

Click the ActiveX button to add a Sybase HTML DataWindow DTC. Use the chart in Table 2 to fill in the property sheet.

The "Link To" tab lists all of the "linkable" objects contained within the DataWindow, such as columns, text and computed fields. Any one of those can be rendered as a hyperlink in the Web DataWindow. You can also create multiple hyperlinks, one for each object listed. We need to link the department name column to the employee page. Click on the empty box to the right of the "dept_name" column. You should see the "Link Definition" dialog, as in Figure 3. Search for a URL and choose "Employees.htm". Knowing that the employee page has a "dept_id" page parameter, the dialog will automatically place it in the "Parameters" section. But how will you pass a value for department ID? We have the "dept_id" column in our department DataWindow. So click in the "Value Type" drop-down and select "Database Column" from the list. Then click in the "Value Expressions" drop-down and select "dept_id." We're almost done, but remember that our department page is going to be displayed in the left frame of a frameset, and we want the employee page to display in the right frame. So type "right" as the "Target" (this is case sensitive, so be sure to use the same name as your frame). Now you can click OK.

Close the page and save your changes.

Deploying the Web Site
At this point you're almost ready to view your Web site in the browser. But first you have to deploy your pages to the Web server. In the PowerSite Project view, if your pages are still marked as "Local," select them all, right-click and check them into the Component Manager. (If you need to edit them later on you'll need to check them out.) Right-click again and select "Default Deploy." This will deploy your pages to the DW-DTC PowerDynamo site. Now you can go to your browser and enter your Web site's URL: http://localhost/dw-dtc/Home.htm. (Make sure you have all the right components running: the EAS Demo DB database, Jaguar and the PowerDynamo Personal Web Server.)

Please note that your Web site won't look identical to Figure 2 in Part 1 of this article (reproduced here as Figure 4) because I made some minor changes:

1. I set a fixed width for the left frame in Home.htm. (You can edit the frameset only on the Source or Structure tabs of the page editor.)
2. I added a background image to the department and employee pages.
3. I made the background color of all of the DataWindows transparent so the page background would show through.

Advanced Control Options
On the "Control" tab of the Sybase HTML DataWindow Properties dialog are options to override the Web DataWindow's "Weight" and "Rows Per Page" (see Figure 5).

The "Name," "Weight" and "Rows Per Page" options correspond to DataWindow properties that can be found in PowerBuilder's DataWindow painter on the "HTML Generation" tab of the DataWindow properties (see Figure 6).

How they match up is shown in Table 3.

Here's how these properties work. When you create a DataWindow in PowerBuilder, by default it will set "Rows Per Page" to zero, and it will check "Generate JavaScript," "Client Events," "Client Validation" and "Client Computed Fields." That's fine, but as you might expect, there are implications to each of these options. If you set "Rows Per Page" to anything but zero, the DataWindow (running in Jaguar) will retrieve all rows but will generate the HTML for the specific number of rows needed. (It's up to you to add buttons to your DataWindow so the user can scroll through the data.) But retrieving all rows just to display a few is a lot of work for the database and the HTML Generator component.

Similarly, there are performance ramifications to checking "Generate JavaScript," "Client Events," "Client Validation" and "Client Computed Fields." Each of these options tells the DataWindow engine to generate additional JavaScript to be downloaded to the browser. Thus your Web DataWindow gets heavier and heavier with each checked box (i.e., there's more HTML to download).

If you don't override any of the options in the Control tab of the Sybase HTML DataWindow Properties dialog, the HTML Generator component in Jaguar uses the properties set in the DataWindow object. If you check "Override," however, and specify options in the HTML DataWindow DTC, those properties are passed on to the HTML Generator component. It would be a good idea to uncheck as many of the HTML Generation checkboxes as possible in the DataWindow painter, based on whether the DataWindow is editable, has computed fields and validation rules, and so forth. But it's more difficult to determine how many Rows Per Page are appropriate in the DataWindow painter. So it's a good idea to leave that set to zero in the DataWindow painter, and if absolutely necessary you can override it in the HTML DataWindow DTC.

One final tidbit on the Control tab regarding the checkbox called "Server Side State Management": this checkbox should rarely be checked, if ever. Checking this box forces the HTML DataWindow component in Jaguar to be stateful. I won't join the many daring souls who have written on the difficult topic of stateful versus stateless components, but I will discuss this specific case as an example. If you were to check this box, the HTML DataWindow component in Jaguar would stay bound to the PowerDynamo session that accessed it. From the client's perspective this would be great, because the next time it accessed the server component the component wouldn't have to reretrieve the client's data, so data access would be faster. The scary part is that the component wouldn't be deactivated until the client requested that the Web DataWindow update some changes or until the client's session timed out in PowerDynamo. That could seriously impact your scalability.

The only setting in which this might be appropriate would be in an intranet setting with a relatively small number of users. Perhaps you have a particular page that retrieves a large number of rows and you want your users to be able to page through the data (e.g., Rows Per Page = 20). A stateless HTML Generator component would have to reretrieve the large result set every time the page was requested, which could be quite slow. With "Server Side State Management" checked, however, your server component wouldn't have to reretrieve the rows as the user paged through the data. But if 50 users accessed that page simultaneously, you'd have 50 stateful components all managing a large result set. There are some serious trade-offs with this option, so it's worth benchmarking to see if you can get performance improvements without killing your server.

Advanced Jaguar Options
Actually, there's only one advanced option to discuss on the Jaguar tab. That's the checkbox labeled "Send transaction data at one time," otherwise known as "One trip." It would be nice to use this option because it reduces the number of calls made from PowerDynamo to set up the HTML Generator component in Jaguar. By default PowerDynamo needs to make several calls to set up the HTML Generator component (as shown later), but with "One trip" checked it makes only one call, which is faster. Unfortunately, this is an option you'd probably never use in this 1.0 version of the HTML DataWindow DTC. Why? Because it requires that you use a custom HTML Generator component that has its DataWindow object preloaded. In other words, for each DataWindow object that you'd want to display as HTML you'd need one custom HTML Generator component (e.g., five different one trip Web DataWindows require five different custom HTML Generator components). This is a ridiculous requirement because the HTML DataWindow DTC can't use more than one HTML Generator component. It has the name "DataWindow/HTMLGenerator" hard-coded into its server-side JavaScript. I simply can't think of a reason why you'd use the "One trip" option in its current form unless you didn't use the HTML DataWindow DTC but instead coded your own Web DataWindows in JavaScript. Maybe that will change in the next version.

HTML DataWindow DTC Source Exposed!
So you fill out the property sheet of the Sybase HTML DataWindow DTC, but what does the DTC actually do? First, it embeds the selections for the DTC in your HTML source. Second, and most important, it generates JavaScript (see Listing 1). I won't go into the details of how the HTML DataWindow DTC stores its settings in your HTML. It's more important to understand the JavaScript it generates.

You can pretty much figure out the code for yourself. The first four lines of JavaScript instantiate classes:

1. PSJaguarConnection is responsible for connecting to Jaguar.
2. PSDataWindowSourceClass is responsible for accessing your DataWindow object.
3. PSConnectionParmsClass is responsible for setting up the database connection.
4. PSDataWindowClass is the main class responsible for setting up the HTML Generator component and using it to generate HTML.

The last two lines set up the column link and generate the final HTML. That completes the six lines of JavaScript that the HTML DataWindow DTC spits out, but it's not the whole story. I won't go into the details of JavaScript, but I will tell you that those classes are not standard JavaScript classes. Those classes are defined in a JavaScript file called "ObjMod.ssc" that is included in your deployed HTML file. You don't see any reference to that file when you view your HTML source code in PowerSite, but if you open the source of your Web page in Sybase Central, you'll see the following lines of code at the top of the source:

<!--SCRIPT PSOBJMOD=TRUE
import( site.GetRootDocument().location + "/ObjMod.ssc" );
session.active = true;
InitObjects(session);
-->

The file "ObjMod.ssc" is often referred to as the PowerSite Object Model. (In PowerSite's InstaHelp look up "object model, PowerSite.") It includes the class definitions of the four classes mentioned above and many others. If you're using Active Server Pages, there's another version of the object model, "ObjMod.js". Either way, when you deploy your HTML page, PowerSite adds the server-side include and also deploys the appropriate object model (ObjMod.ssc or ObjMod.js). If you'd like to learn some advanced JavaScript, or you want to understand the Web DataWindow in greater depth, take a look at ObjMod.ssc. It's right there in Sybase Central next to your HTML pages.

Limitations of the HTML DataWindow DTC
First of all, let's not forget that this is version 1.0 of the Web DataWindow. I think most people were extremely surprised when word of the Web DataWindow got out. Thin-client PowerBuilder? Unheard of! But as a 1.0 release you must expect some limitations. I'll list a few that I've encountered. (I won't repeat the limitation I already described above regarding the "One trip" option.)

After building a few simple Web DataWindow pages, you might decide to try something fancy, like creating some custom HTML Generators or writing your own version of ObjMod.ssc. Unfortunately, using the Sybase HTML DataWindow DTC eliminates those options. As I mentioned above, the HTML DataWindow DTC and ObjMod.ssc both have the name "DataWindow/HTMLGenerator" hard-coded in them. While it sure would be nice, you can't use the DTC with an HTML Generator component of any other name. While you can customize the HTML Generator component named "DataWindow/HTMLGenerator," others with different names are out of the question. Likewise, you can't customize ObjMod.ssc to change its behavior. Even if you open it in Sybase Central and make changes, those changes will be overwritten the next time you deploy a page using the PowerDynamo deployment controller in PowerSite. That's because the source code for ObjMod.ssc is embedded in the deployment controller itself and it's redeployed with every page that uses the PowerSite object model. So you're stuck with DataWindow/HTMLGenerator and ObjMod.ssc. Really, that's not so bad.

Beyond the Sybase HTML DataWindow DTC are some noteworthy limitations to PowerSite and to the HTML Generator. I give PowerSite high marks for its ease-of-use features, like the System Tree and InstaHelp. Its flexible and open deployment controllers are pretty cool too. But its WYSIWYG HTML editor leaves plenty of room for improvement (FrontPage 2000 is much nicer). And finally, while its scripting environment is better than some others (Visual Interdev?), it's definitely not like developing in PowerBuilder. How about some compile-time syntax checking, for example? We can't excuse PowerSite by saying it's a 1.0 release, but I expect it will do some catching up soon.

Finally, there are some limitations with the HTML Generator component that ships with EAStudio with reference to the lack of straightforwardness in processing business logic for Web DataWindows. However, other articles have already addressed the topic of customizing the component and using HTML Generator service classes. In addition, you might want to take a look at Dynamic Data Solution's Enterprise Application Framework. They've heavily customized the HTML generator, and even written a replacement for ObjMod.ssc. But of course that solution wouldn't work with the HTML DataWindow DTC.

Closing Thoughts
While most articles discussing the topic of Web DataWindows have used raw JavaScript instead of PowerSite's Sybase HTML DataWindow DTC, I believe the DTC is the most productive development option for most developers. Following the 80/20 rule, the HTML DataWindow DTC provides nearly all of the functionality of manually coded Web DataWindows, but with significantly less effort. In addition, Sybase stated at last year's TechWave that they're putting a lot of effort into enhancing their Web development IDE to make it nearly as easy and flexible as developing in PowerBuilder. And you can bet there'll be some great enhancements to the HTML DataWindow DTC! So it seems like a good time to study up on PowerSite and the HTML DataWindow DTC, precursors to the next-generation Sybase Web development IDE.

• Figure 1
• Figure 2
• Figure 3
• Figure 4
• Figure 5
• Figure 6
• Source Code
• Figure 7
• Figure 8
• Figure 9