Release 10.1A: OpenEdge Development:
ADM and SmartObjects

> ## 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 prior 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:

> - The master file `src/adm2/pnavlbl.w` has buttons with labels.

> - The master file `src/adm2/pnavico.w` has buttons that resemble VCR icons.

> 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:

> - First invokes `fetchFirst`.

> - Prev invokes `fetchPrev`.

> - Next invokes `fetchNext`.

> - Last invokes `fetchLast`.

> 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). 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 on.

> ##### 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 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, 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`:

> - Save invokes `updateRecord`.

> - Add invokes `addRecord`.

> - Reset invokes `resetRecord`.

> - Copy invokes `copyRecord`.

> - Delete invokes `deleteRecord`.

> - Cancel invokes `cancelRecord`.

> In Update mode, choosing the Save, Add, Reset, Copy, Delete, and Cancel buttons invoke 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.

> 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 `PUBLISH`es `commitTransaction` and the Undo button `PUBLISH`es `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: 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), 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.

> 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 the modifications to the database in a single transaction. If errors occur, the updates continue (if possible), to identify all errors with the update, the transaction is undone, and the errors are 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 were not 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 several ways:

> - Instance properties — The SmartPanels have an instance properties dialog box (source program `src/adm2/support/n-paneld.w` for Navigation panels and `src/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 Microsoft Windows). You can modify the number of edge-pixels or suppress the rectangle altogether by setting the value of the EdgePixels instance property to 0 (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 Chapter 2, " SmartObjects."

> - Resizing 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.

> - 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 a button is present before enabling or disabling it.) For example, you can remove any buttons from the Navigation SmartPanels to create a smaller custom Navigation panel. You also can remove buttons from the Update SmartPanels.

> Caution: Do not remove from Update SmartPanels any buttons needed to complete update operations. You cannot remove the Save/Update button. If Add or Copy is present or a panel based on the Standard Update panel is in Update mode, do not remove the Cancel button.

> You also can add buttons with user-specific functionality to a custom SmartPanel. See Chapter 6, "Advanced ADM Topics," for more information on building custom SmartObjects.

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