Progress
ADM 2 Guide


Using SmartPanels

Progress provides prebuilt masters for three SmartPanel types: Navigation, Update, and Commit. You can modify these masters to create new SmartPanels with specialized functions, so the ADM does not include a SmartPanel template.

In previous ADM releases, a common use for the Navigation and Update SmartPanels was to place both a Navigation SmartPanel and an Update SmartPanel in a Progress application and use them collectively as a sort of toolbar. If the containing SmartObject is a SmartWindow, this is no longer necessary, as you can provide this combined functionality with a SmartToolbar. (See the "Using SmartToolbars" section.)

Navigation SmartPanels

Two prebuilt SmartPanels are designed to navigate through a set of records; they support the Navigation link type. These panels contain buttons that represent the functions First, Previous, Next, and Last. They differ only in how they represent these buttons:

Choosing these buttons publishes the following ADM events (implemented in the procedure src/adm2/query.p), which are received in the SmartPanel’s Navigation–Target:

The standard SmartObject designed to be a Navigation–Target is the SmartDataObject. However, if you want your users to be able to use buttons to navigate through records, use a SmartDataBrowser as a visualization for a SmartDataObject. In this case, moving through the rows of the SmartDataBrowser navigates through the SmartDataObject query (although the SmartDataBrowser is not actually the Navigation–Target). Note that the SmartPanels know nothing about the data through which they help to navigate. A custom SmartObject with these four ADM procedures could use them to navigate through any kind of data, including pages in a report, segments of a video, and so forth.

Update SmartPanel

Another prebuilt SmartPanel contains buttons for modifying records. This SmartPanel, which uses the TableIO link type, can serve as a TableIO–Source for a SmartDataViewer, SmartDataBrowser, or other SmartObject that is a TableIO–Target.

The master file src/adm2/pupdsav.w is called the Standard Update SmartPanel. You should use this SmartPanel to modify database records. It has six buttons and runs in one of two modes, or styles, that you can set in the SmartPanel’s Instance Properties dialog box: Save mode and Update mode:

Choosing the buttons of the Standard Update SmartPanel in Save mode invokes the following methods, which are found in the super procedure src/adm2/datavis.p, as well as in the SmartDataBrowser- and SmartDataViewer-specific super procedures src/adm2/browser.p and src/adm2/viewer.p:

In Update mode, choosing the Save, Add, Reset, Copy, Delete, and Cancel buttons invokes the same methods as in Save mode. In addition, choosing the Update button invokes enableFields.

See the online help for more information on the functions of these procedures and functions.

Note that the Standard Update SmartPanel has no direct role in managing database transactions. It merely invokes the procedures and functions named. All actual data access, locking, and transaction management are handled by the super procedures for the SmartDataObjects themselves.

Commit SmartPanel

The Commit Panel SmartObject includes two buttons: Commit and Undo. The Commit button PUBLISHes commitTransaction and the Undo button PUBLISHes undoTransaction.

The Commit SmartPanel, pcommit.w, defines the CommitTarget property and CommitTarget event. The panel subscribes to the RowObjectState in its Target. The RowObjectState procedure takes either NoUpdates or RowUpdated for parameters. These states disable or enable the panel buttons.

When you use a Commit Panel, the SmartDataObject is made a Commit–Target and the panel is a Commit–Source. The SmartDataObject sets the AutoCommit property to No if it has a Commit–Source.

The data.p super procedure includes the commitTransaction and undoTransaction event procedures. See the online help for more information on these procedures.

NOTE: You should use the Commit SmartPanel only when your application must specifically allow users to batch multiple updates to be committed at the same time; for example, to allow a set of order-line records for an order to be added or updated together. In other cases, using the Commit Panel is unnecessary and can complicate the update process.

SmartDataObjects have an AutoCommit property that indicates whether, on update (Add, Save, Copy, or Delete operations), changes should be written back to the database as each individual record is saved (or deleted). By default, the AutoCommit property is set to YES. When this is the case, the following happens each time the Save or Delete button is pressed (or an equivalent updateRecord or deleteRecord operation occurs in some other way):

  1. The before and after image of the single row that is being updated is written into an additional temp–table called RowObjUpd. For a discussion of this temp–table, see the "SmartDataObject Query and Update Operations" section in Developing Your Application’s Business Logic."
  2. If the SmartDataObject is divided between client and AppServer, the row is passed back to the AppServer.
  3. The change is made to the database.

However, if a SmartDataObject has a Commit–Source (normally the Commit SmartPanel), the AutoCommit property is automatically set to NO. In this case, each time the Save or Delete button is pressed, the relevant RowObject row is written to the RowObjUpd temp–table, but the changes are not written back to the database. To write the updates to the database, the application user presses the Commit button, which executes the commitTransaction procedure in the SmartDataObject. This procedure sends the RowObjUpd table back to the server, then opens a transaction block and makes all of the modifications to the database in a single transaction. If errors occur, the updates continue (if possible) in order to identify all errors with the update, the transaction is then undone, and the errors are then returned to the client for correction. If no errors occur, all the updates are written to the database in a single transaction block.

Pressing the Undo button, which executes the undoTransaction procedure, has the effect of reversing the current Commit operation. This procedure cancels all updates that have not been committed, empties the RowObjUpd temp–table, and returns the RowObject temp–table to its state before the first of these updates was made.

Customizing SmartPanels

You can customize the SmartPanel objects in a number of ways.


Copyright © 2004 Progress Software Corporation
www.progress.com
Voice: (781) 280-4000
Fax: (781) 280-4095