This chapter introduces the concept of dynamically generated pages and discusses how to evaluate your application from a design perspective. It also provides a brief overview of maintaining page state and basic information about the SilverStream page development environment. It covers the following topics:
With the SilverStream Page Designer, you create dynamic HTML pages that are implemented in Java. Objects on the server represent the HTML controls for a page. Each object has properties, events, and methods. For example, you can adjust a text field's Width property and code its validationTest event.
Server-side Java code implements the pages and controls internally. SilverStream automatically generates the HTML returned to the browser at runtime, based on the current values of the control objects.
This diagram shows how the Page Designer relates to the objects and to the generated HTML.
You create controls, such as text fields and buttons, in the Page Designer. The server treats them as objects to be created at runtime. The server handles communication with the browser and coordinates events between the page and controls. The browser receives the final output as HTML to display on the screen.
You can programmatically change many properties of the controls at runtime by calling accessor (get or set) methods.
You can extend the page environment by writing your own methods and creating custom controls. The Application Program Interface (API) for pages and page controls is documented in the help system.
While SilverStream shields the programmer from some complexity, designing pages does require an understanding of Web languages, protocols, and techniques. In particular, having a basic understanding of the following concepts will help the page programmer:
The following situations trigger page events:
showPage().
When a submit occurs, the browser sends the changed data to the server. The server passes the data to each control object. When a control object detects a change in its value, it triggers a valueChanged event.
At the end of all the data changes in the request, the server processes the submit action. The control that caused the submit fires a pageActionPerformed event.
Finally, after processing the data change events and the submit action, the server generates the HTML to return to the browser. The page iterates through each control to determine how to render it in HTML.
Additionally, page events precede and follow the events that the controls fire. Most programmer code takes place between the pageRequestBegin event and the pageGenerateBegin event. The following diagram summarizes the event flow.
The following table describes the page and control events for which you typically write code.
NOTE By default, only a text button generates a submit request. You can make other controls send a submit by checking the Submit On Change checkbox in the Property Inspector. This only works for JavaScript-enabled browsers.
Also see the section
Writing code on events, which discusses the best use of events for writing code.
The SilverStream page design environment supports numerous industry standards.
SilverStream supports HTML standards.
SilverStream implements pages as servlets according to the JDK 1.2 specification. Pages can also interact with servlets that are written as business objects.
JAR files store the page controls as JavaBeans. You can access their methods, events, and properties. Programmers and third parties can add their own custom controls.
The absolute positioning control, also called the layout region control, allows you to align the controls more precisely. You can place controls on it as you would on a grid. SilverStream generates the absolute positioning region as a collection of nested HTML tables in the browser. The runtime display of tables, particularly in older browsers, is sometimes very slow; therefore, the absolute positioning control isn't appropriate for all applications.
For more details on using absolute positioning control, see
Programming Pages.
You can arrange multiple pages in a single browser window using framesets. Framesets might display banners, navigation buttons, choices, and selected details in certain areas of the screen. Clicking on an item in one frame typically opens a new page of more detailed information in another frame. When you create a new page in SilverStream, you have the choice of creating either a regular page or a frameset.
For details about framesets, see
Programming Pages.
The Page Designer allows you to write JavaScript code. JavaScript runs in a browser. It can validate data, display alert messages, and change the values of other controls.
For more details about adding JavaScript enhancements to a page, see
Advanced Page Topics.
SilverStream complements Dynamic HTML (DHTML). A browser might implement DHTML by extending JavaScript and style sheets. DHTML enhances the user interface in a browser-specific manner.
Most built-in page controls appear in the Programming Editor so that you can code responses to their events. You can also make other page controls, such as applets, images, and text, into programmable objects. This lets you change their properties at runtime.
For details on making page controls programmable, see
Programming Pages.
When designing your pages, you will want to evaluate the requirements of your application. Some questions to consider are:
Static HTML pages contain information that does not change. These pages typically contain corporate banners, navigation, and menu choices. SilverStream lets you create static HTML pages. However, the real power of SilverStream is its support for dynamically generated pages.
Dynamically generated pages allow you to:
This dynamic generation of HTML happens automatically when you use SilverStream's Page Designer controls.
The type of browser your users have and how well you know your users will influence your design decisions.
When you do not know your users or they are not likely to spend much time at your Web site, you might choose to include only HTML without any Java or JavaScript. This option provides you with the largest possible base of customers for deployment, since your users will not need a browser version that supports Java or JavaScript. Users also will not have to wait for Java classes to download.
By only using HTML, you limit your data validation choices. Without the use of JavaScript, any data validation you need will have to take place on the server. This takes additional time, uses more network bandwidth, and causes the screen to repaint every time the server needs to evaluate a page.
You may also give up some control over the formatting of your page by not using Java, since the appearance of HTML controls is only approximated in the Page Designer. The browser can adjust the sizes and the exact implementation of certain controls. For example, the browser may decide to display a choice control either as a dropdown list or as a regular list box. If total control over appearance is important, you might want to use Java forms or views on your page. See the chapters describing the Form Designer and the View Designer for more information about creating Java forms and views.
JavaScript performs certain tasks in the browser quickly and avoids repainting the screen in many situations. It is provided by the browser and does not require the user to wait for a download.
To take advantage of JavaScript functionality, the user must have a later browser version, which might affect your design decisions. JavaScript is available in the 4.0 versions of Netscape and Internet Explorer. JavaScript is also available in some earlier versions, such as Netscape 3.0 and Internet Explorer 3.02, but those versions differ significantly from the 4.0 versions.
JavaScript can enhance your pages by:
A very common use of JavaScript is to validate data without having to access the server.
JavaScript cannot talk directly to the server, and it cannot access files.
You can place any Java form or Java view (created with the Form Designer or View Designer) on a page. These forms and views contain Java code that runs on the user's machine, whereas the Java code you write in the Page Designer's Programming Editor runs on the server.
NOTE Including forms and views in pages is not supported in SilverStream Version 3.0 due to limitations of the Sun Java 1.2 browser plug-in. We hope to re-enable this support in SilverStream in the future. See the release notes for updated information.
When your page contains both Java controls (forms and views) and HTML controls, a request to the server resets the data in the Java controls. SilverStream recommends that you have only Java controls or only HTML controls on a page, but not both.
SilverStream provides advanced mechanisms for storing persistent information about pages. The page itself has state that the server remembers. Member variables defined on the page object can maintain the state of a single page between requests.
SilverStream also features the ability to store state information in the user session. This is important in a multi-page application. For example, you might need to keep track of items that the user has selected from various pages. Or you might need to control the order of pages, which can be accomplished by checking a page ID remembered in the user session. All pages and business objects within the same session can access information stored in the session.
Calling setSessionValue() with a key name and a value stores information in the session. To retrieve the value later, call getSessionValue() using the name you previously gave to the value.
For an in-depth discussion of various page programming models and using the session object, see
Programming Pages.
SilverStream provides many built-in page controls. HTML programmers might be familiar with text fields, text areas, labels, buttons, checkboxes, radio buttons, choice and list boxes, tables, images and hotspots, lines, links, and tags.
SilverStream also provides file attachments, tab panels, data views, HTML data controls, data controls, plug-ins, applets, ActiveX objects, subpages, and presentations of Java forms and views.
The following table shows the class associated with each control object. See the online help system for descriptions of the properties, events, and methods for the controls. The SilverStream package com.sssw.shr.page contains the page and page control classes.
The Property Inspector provides a property called Enable HTML Generation that lets you specify at design time whether a particular control should appear in the generated HTML. SilverStream also allows you to enable or disable HTML generation for controls programmatically. To enable or disable HTML generation for a control at run time, you need to call the SetEnableHTMLGeneration() method for the control.
The Page Designer supports a wide variety of page layouts, including the placement of controls inside other controls. For example, you might drop a button control onto the pane of a tab panel.
The button then appears only when the user selects the pane on which the button is located.
The Page Designer also supports more complex combinations of controls. For example, you can drop a tab panel into an absolute positioning region.
You can place a Java form or view (created with the Form Designer or View Designer) onto a page.
You can drop a data view or an absolute positioning region into a tab panel.
A control placed inside another control can have additional controls of its own. Thus, a tab panel might contain an absolute positioning region, which itself could contain text and buttons.
SilverStream provides three instance variables in the Page Designer. These instance variables allow you to call methods on them without having to instantiate the objects. You can find and select these instance variables from the list of callable objects in the Programming Editor.
The three instance variables available to pages are agData, agDataMgr, and agScriptHelper. They are described in the following table.
In the following example, the agScriptHelper instance variable displays a message. You could place this code in the page's pageLoaded event to display the message when the page is first requested.
agScriptHelper.alert("Thank you for signing in!");
A page you create in SilverStream can serve an arbitrary set of URLs. Therefore a single page can satisfy multiple URL requests. To specify the URLs associated with a page:
Each URL you specify is relative to http://server/database, not http://server/database/SilverStream/Pages, as is the case with the default URL for a SilverStream page.
NOTE When you specify one or more URLs for a page explicitly, the default URL for the page will no longer work.
You can specify the default URL that the server brings up when the user requests the URL for the database as well as for the server. You set these properties in the SilverStream Designer.
The Default Database URL property controls which URL the server shows when the user requests the URL for the database. The Default Server URL property controls which URL the server shows when the user requests the URL for the server. The following table shows examples:
Only one page at a time within the same database can have the Default Database URL property checked. When you mark this property checked on one page, SilverStream will automatically uncheck any other page in the database that previously had this property checked. The same is true for the Default Server URL property.
You can test a page by choosing the Run icon from the Page Designer. This launches your browser and displays the page. You can also use the SilverStream Debugger to debug pages.
To specify which browser should be used for testing and debugging, select Edit>Preferences in the SilverStream Designer and specify the executable for the browser in the Browser field on the General tab of the Preferences dialog.
When testing pages that contain Java forms or views, you need to specify a batch file in the Browser field rather than an executable. The batch file must set the CLASSPATH and start the browser program. You can simply clear the CLASSPATH (as shown below) or specify path information that suits your application requirements:
set classpath=
start iexplore %1 %2 %3 %4 %5
The SilverStream Debugger lets you locate runtime bugs in your Java applications by controlling and monitoring the execution of Java source code. It helps you find and fix errors.
You can use the SilverStream debugger to debug pages. The pages can be running locally or on a remote machine. You can invoke the Debugger either from the Programming Editor in the SilverStream Designer or as a separate process.
For more information about the SilverStream Debugger, see SilverStream Debugger in the online Tools Guide.
While testing your pages, you might find useful information within the browser by viewing the HTML source that the server generated.
If you are having trouble getting the page to display in the browser, you can view the console messages. To see the console window, select View>Server Console in the SilverStream Designer.
You can increase the amount of information you see in messages that appear in the console as follows.
See the chapter on troubleshooting in the Administrator's Guide for more information.
You can add println() statements to your code to help debug your page. These messages appear in the console window. The following sample debugging lines print text messages and the value returned by a method.
System.out.println("Page Request Begin event triggered.");
System.out.println("agData has children = " +
agData.hasChildren());
To display line numbers along with the code, select Edit>Show Line Numbers in the Programming Editor.
If an exception was thrown by your page, the browser shows an error message generated by SilverStream. You can click on a link in the message to see more details.
By default, Internet Explorer 5 returns its own HTML error page for common HTTP error messages. To view the SilverStream error page instead: