skip to main content
OpenEdge Development: ADM and SmartObjects
Data Management in the ADM : Using SmartPanels and the SmartToolbar
 
Using SmartPanels and the SmartToolbar
A SmartPanel is a group (or panel) of buttons that send messages to other SmartObjects. There are several types of SmartPanels, which you can use to manage records in various ways: navigate through them, update them, or perform transaction processing. The SmartToolbar provides a toolbar and/or menu interface for performing one or more of these operations, as well as some additional operations not discussed in this chapter.
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 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: 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.
Using SmartToolbars
A SmartToolbar is a SmartObject that provides a toolbar and/or menu interface to application commands that perform various actions; for example, performing navigation and transaction actions in the current object. You can contain a SmartToolbar in a SmartWindow but not in a SmartFrame or a SmartDialog, and you can put only one SmartToolbar instance in a given SmartWindow.
Progress provides the prebuilt master toolmenu.w for the SmartToolbar. You can modify this master to create a new SmartToolbar with specialized functions, so the ADM does not include a SmartToolbar template.
By default, a SmartToolbar instance includes both a toolbar and a menu. See the “Customizing SmartToolbars” section for information on changing this.
The SmartToolbar provides the application user with the ability to perform the following groups of actions:
*Navigation operations — First, Prev, Next, Last. For information on these actions, see the “Navigation SmartPanels” section.
*TableIO operations — Either of the following:
*TableIO Save operations — Add record, Copy record, Delete record, Save record, Reset, Cancel.
*TableIO Update operations — Add record, Update record, Copy record, Delete record, Save record, Reset, Cancel.
For information on these actions, see the “Update SmartPanel” section.
*Commit operations — Commit, Undo. For information on these actions, see the “Commit SmartPanel” section.
*Filter operation — For information on this action, see the “Filtering records” section.
By default, only the Navigation and TableIO Save operations are enabled. You can specify that the user can perform all or a subset of these actions. See the “Customizing SmartToolbars” section. Which action groups you select determine whether the SmartToolbar functions as a Navigation-Source or a TableIO-Source or both. The wizard prompts you with possible connections.
The rules and data for the actions accessible in the SmartToolbar are defined in an action class from which the SmartToolbar inherits and are totally independent of the SmartToolbar’s layout and structure. As a result, all SmartToolbar actions have the same text, image, and interface throughout the application regardless of the SmartToolbar layout.
Customizing SmartToolbars
The simplest way to customize the SmartToolbar object is through its instance properties. The SmartToolbar has an instance properties dialog box (source program: src/adm2/support/toold.w) that you can use to specify properties in a run‑time instance of a SmartPanel without modifying the master object itself:
*You can choose to show either a menu or a toolbar or both.
*You can choose to show a decorative border rectangle around the toolbar; the border includes dividers between icon groups.
*You can specify which actions the application user can perform from the SmartToolbar.
For descriptions of the SmartToolbar instance properties, see Chapter 2, “SmartObjects.”
More complex SmartToolbar modifications (for example, the order and structure of icons and menus) involve modifying the SmartToolbar object itself. For basic information, see the “Complex SmartToolbar modifications” section.