Programmer's Guide



Chapter 9   Page Basics

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:

About SilverStream pages   Top of page

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.

Background concepts   Top of page

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 page event model   Top of page

The following situations trigger page events:

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.

Event

Description

processPathInfo

Fired before all other events on the page if the URL specifies a path following the page (or servlet) name. The path tells the page what action to perform. Use this event to examine the specified path and perform application-specific processing.

pageLoaded

Fired on the page the first time in the session that it is requested. Perform one-time initializations here.

pageRequestBegin

Fired on the page every time a request is sent, including the first time. Use this event to handle request-level actions, such as a query.

validationTest

Fired on certain controls when their values have changed. You can check to see if the data is valid. Failure triggers the validationFailed event.

validationFailed

Fired when a change fails a validationTest event.

globalValidationTest

Fired on the page to perform page-wide validation of all controls. Failure triggers the globalValidationFailed event.

globalValidationFailed

Fired when a globalValidationTest event fails.

valueChanged

Fired on controls whose changes are valid. The first time a page is requested, the valueChanged event fires before the pageLoaded event for bound controls on the page.

pageActionPerformed

Fired on the control that caused the submit request.

pageGenerateBegin

Fired on the page after handling changes and actions for the controls. Begins the generation of HTML and JavaScript.

pageRequestEnd

Fired on the page after HTML and JavaScript generation. Perform request-level cleanup here.

handlePageException

Fired on the page if an exception was thrown during the event processing. This gives you a chance to customize how the page handles exceptions.

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.

Supported standards   Top of page

The SilverStream page design environment supports numerous industry standards.

HTML standards

SilverStream supports HTML standards.

Servlet standard

SilverStream implements pages as servlets according to the JDK 1.2 specification. Pages can also interact with servlets that are written as business objects.

JavaBean standard

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.

Absolute positioning   Top of page

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.

Framesets   Top of page

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.

JavaScript   Top of page

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.

DHTML   Top of page

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.

Programmable page objects   Top of page

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.

Design requirements   Top of page

When designing your pages, you will want to evaluate the requirements of your application. Some questions to consider are:

Dynamic behavior   Top of page

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.

Browser requirements   Top of page

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 functionality

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.

Java forms and views on a page

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.

Page state maintenance   Top of page

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.

Built-in controls   Top of page

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.

Control

Associated class

Common uses of control

ActiveX

AgpActiveObject

Handles an ActiveX object.

Applet

AgpApplet

Handles a Java applet.

Cell

AgpTableCell

Handles formatting of a box inside a table, data view, layout region, or tab panel.

Checkbox

AgpButtonCheck

Displays and allows setting of a true/false value.

Choice Control

AgpChoice

Presents a dropdown list of choices.

Data

AgpData

Accesses additional data, beyond the primary data table for the page.

Data View

AgpViewPanel

Displays data in a table format.

File Attachment

AgpFileUpload

Uploads a file to the server.

Frame

AgpFrame

Divides a page into sections that contain other pages.

HTML Data Control

AgpHTMLControl

Inserts raw HTML.

Image

AgpImage

Enhances page appearance with graphics; can function as a button.

Image Hotspot, rectangular or oval

AgpImageHotSpot

Allows the user to bring up another page or perform an action by clicking on a specific portion of an image.

Label (also known as the Data tag)

AgpLabel

Displays literal text or text that results from an expression. Can function as a link.

Layout Region

AgpLayoutPanel

Arranges controls at specific positions on the page. Also called absolute positioning.

Line

Special type of AgpParagraph

Visually separates areas of the page with a horizontal line.

Link

Special type of AgpText

Allows the user to navigate to another page.

List Box

AgpList

Presents a selection list of multiple values.

Page

AgpPage

Handles properties, events, and methods for the page.

Paragraph

AgpParagraph

Formats a paragraph of text.

Plug-in

AgpPlugIn

Handles a plug-in.

Presentation

AgpPresentation

Includes a Java form or view on this page.

Radio Button

AgpButtonRadio

Displays and allows setting of a single value from a set of choices.

Subpage

AgpPage

Includes another page as part of this page.

Tab Panel

AgpTabPanel

Contains panes of information. Only the current pane's contents are displayed.

Table

AgpTable

Presents information in a table format.

Tag

AgpTag

Inserts additional HTML information.

Text

AgpText

Formats a selection of text.

Text Area

AgpTextArea

Displays and allows entry of multiple lines of text.

Text Button

AgpButtonText

Performs an action, such as submitting a request to the server.

Text Field

AgpTextField

Displays and allows entry of a single line of text or numbers. Can handle passwords and can be hidden.

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.

Controls within other controls   Top of page

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.

Complex control combinations   Top of page

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.

Helper instance variables   Top of page

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.

Instance variable/

Class name

Purpose

Selected methods available

agData,
an instance of
com.sssw.
shr.page.
AgpDataPrimary

Provides access to the page's primary database table.

clearRows()
haveRowsChanged()
invokeQuery()
query()
refreshRows()
updateRows()

agDataMgr,
an instance of
com.sssw.
rt.event.
AgoBindingManager

Supports dynamic data binding.

beginFind()
bind()
doFind()
evaluateAllExpressions()
isLinkBound()
unbind()

agScriptHelper,
an instance of
com.sssw.
shr.page.
AgpScriptHelper

Performs common JavaScript functions without having to code in JavaScript. Note that this requires the browser to support ECMA JavaScript 1.1 even though you do not have to write the JavaScript yourself.

alert()
closeWindow()
openWindow()
reloadFrame()
reloadTopFrame()
setFrameLocation()

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!"); 

URLs and pages   Top of page

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:

  1. Open the Property Inspector for the page.

  2. Click the URLs button on the Page tab.

  3. For each URL, click the Add button, type a relative URL, and click OK.

    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.

  4. When you've finished adding URLs, click OK.

NOTE   When you specify one or more URLs for a page explicitly, the default URL for the page will no longer work.

Default database URL and default server URL   Top of page

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:

Example URL

Description

Property

http://mycompany.com/

Shows the default URL for this server.

Default Server URL

http://mycompany.com/db1/

Shows the default URL for this database.

Default Database URL

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.

Debugging and testing pages   Top of page

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

Using the SilverStream Debugger   Top of page

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.

Testing tips   Top of page

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.

  1. Bring up the SilverStream Management Console by selecting File>Manage Server in the SilverStream Designer.

  2. Select Configuration options.

  3. Select Advanced panel.

  4. On the Debug tab, change the Client, Business Objects, and SQL settings to 1.

  5. When you are done testing, you might want to reset the values so that performance is not slowed by creating the extra messages.

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:

  1. Start Internet Explorer 5.

  2. Select Tools>Internet Options.

  3. Select the Advanced tab.

  4. Deselect Show friendly http error messages and click OK.






Copyright © 2000, SilverStream Software, Inc. All rights reserved.