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:
- Save mode is the default mode. In Save mode, the updateable fields of the SmartPanel’s TableIO–Target are enabled at all times. The label on the first button is Save. A user can make changes to the current record and choose the Save button to write them back to the associated SmartDataObject.
- Update mode is the nondefault mode. Initially, the label on the first button is Update, and fields in the TableIO–Target SmartDataViewer or SmartDataObject are disabled. When the user locates a record to change, choosing the Update button enables the updateable fields, and the label on this button becomes Save. Choosing the Save button sends the changes to the SmartDataObject, disables the fields again, and resets the label to Update.
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 proceduressrc/adm2/browser.p
andsrc/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):
- 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."
- If the SmartDataObject is divided between client and AppServer, the row is passed back to the AppServer.
- 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.
- Instance properties. The SmartPanels have an Instance Properties dialog box (source program
src/adm2/support/n-paneld.w
for Navigation panels andsrc/adm2/support/u-paneld.w
for Update panels) that you can use to specify properties in a run-time instance of a SmartPanel without modifying the master object itself. For all SmartPanels, you can choose to show a decorative border rectangle around the buttons. The default border is a rectangle with two edge-pixels (giving a chiseled look in MS-Windows). You can modify the number of edge-pixels, or suppress the rectangle altogether by setting the value of the EdgePixels instance property to zero.For the Navigation SmartPanel with icons, you can choose to make the VCR icon on the left the First button (the default) or the button on the right (for countries where text is read from right to left). This corresponds to the instance property RightToLeft.
For descriptions of the SmartPanel instance properties, see SmartObjects."
- Resizing the SmartPanels. You can resize a SmartPanel at design time by grabbing its resize handles and reshaping the panel. The resizeObject procedure in the super procedure
src/adm2/panel.p
(used by all SmartPanels) resizes and rearranges the buttons (in a column or in multiple rows if necessary) to fit the available space.CAUTION: Do not remove from Update SmartPanels any buttons that are needed to complete update operations. You cannot remove the Save/Update button. If Add or Copy is present, or if a panel based on the Standard Update panel is in Update mode, do not remove the Cancel button.- Creating custom SmartPanels. You can create a custom SmartPanel by deleting one or more buttons from a SmartPanel and saving the result as a new SmartPanel. (Code in the SmartPanel master files verifies that a button is present before enabling or disabling it.) For example, you can remove any of the buttons from the Navigation SmartPanels to create a smaller custom Navigation panel. You can also remove buttons from the Update SmartPanels.
You can also add buttons with user-specific functionality to a custom SmartPanel. See "Advanced ADM Topics," for more information on building custom SmartObjects.
Copyright © 2004 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095 |