Progress
ADM 2 Guide
Pass-through Links
Applications invariably contain SmartObjects that are subordinate to SmartContainers, either because they are contained by them (a SmartFrame inside a SmartWindow or another SmartFrame) or because they are lower in the SmartContainer hierarchy (a SmartWindow that is defined as the logical child of another). In some cases, you must be able to connect a SmartObject outside of the containing or parenting SmartContainer with its subordinate SmartObject even though you have direct access only to the SmartContainer. A SmartObject inside a SmartContainer cannot link directly to a SmartObject external to the SmartContainer at design time. However, you can create a two-step link called a pass-through link that allows the two objects to communicate. In a pass-through link, the outer SmartObject is the Source for the containing or parenting SmartContainer and the containing or parenting SmartContainer is the virtual Source for the contained SmartObject.
Figure 3–1 illustrates the two-step pass-through link.
Figure 3–1: Pass-through Link
![]()
The simplest way to explain how to set up a pass-through link is to use an example. Suppose that you build a special SmartFrame, called an Order SmartFrame, that contains these SmartObjects:
You create the Order SmartFrame, as a package; that is, as a single reusable object. You want to use an instance of this SmartFrame to display and update Orders for a particular Customer, an operation that requires passing Customer keys (the Cust–Num fields) from a SmartObject outside the SmartFrame to the SmartDataObject that it contains. Your application will have as its basis a SmartWindow that will contain an instance of your special SmartFrame and a SmartDataObject and SmartDataBrowser for Customers. You will link the SmartObjects in the SmartWindow so that each time an application user selects a Customer, the SmartDataObject inside the Order SmartFrame receives the Cust–Num value and reopens its query for Orders of that Customer; that is, the Order SmartDataObject will be the Data–Target of the Customer SmartDataObject. Because the containing SmartFrame is between these SmartDataObjects, you cannot link them directly and must establish a pass-through link. In one part of this link, the Order SmartFrame is the virtual Data–Source for its Order SmartDataObject. In the other part of this link, the Customer SmartDataObject is the Data–Source, and the Order SmartFrame is its Data–Target.
You must build the your application in a specific order:
At run time, the ADM combines the two separate connections into a single link.
When you build your Order SmartFrame, you define the SmartFrame as the virtual Data–Source for the SmartDataObject that it contains in the Link Editor. To do this, you select THIS–PROCEDURE (which indicates the SmartFrame container that you are building) as the Data–Source and the Order SmartDataObject as the Data–Target. You then tell the Order SmartDataObject to expect a Cust–Num key from its Data–Source at run time. The Link Advisor in the AppBuilder cannot do this automatically because the objects are not in a single SmartContainer. Therefore, you must set the ForeignFields property of the Order SmartDataObject so that it expects Customer keys. To do this, define a createObjects procedure in the SmartFrame with this code:
The RUN SUPER statement runs the standard behavior for createObjects. This runs the AppBuilder-generated adm–create–objects procedure, which creates all of the objects in the SmartFrame and establishes the necessary links. After the standard createObjects procedure executes, the setForeignFields function tells the SmartDataObject to expect to receive the Cust–Num field from its Data–Source and to use it to match the Order.Cust–Num field in its own query.
Figure 3–2 illustrates the established inner connection.
Figure 3–2: Pass-through Link: Inner Connection
![]()
You now create a SmartWindow into which you place a Customer SmartDataObject and SmartDataBrowser. Next, drop your Order SmartFrame into the SmartWindow. You want to pass Customer keys to that SmartFrame so that they get to the Order SmartDataObject inside it. You also do this in the Link Editor, by choosing the Customer SmartDataObject as the Data–Source and the SmartFrame as its Data–Target. Theoretically, when you run this SmartWindow, you will have two Data links, one from the Customer SmartDataObject to the SmartFrame, and one from the SmartFrame to the Order SmartDataObject, as shown in Figure 3–3.
Figure 3–3: Pass-through Link: Inner and Outer Connections
![]()
However, the SmartFrame is not prepared to deal with the Customer keys: the two Data links must be combined into one so that the Customer SmartDataObject and the Order SmartDataObject can communicate directly with each other. To accomplish this, the addLink procedure, which establishes links, notes that the SmartFrame container is both a Data–Target and a Data–Source (this makes the Data link a potential pass-through link) and modifies the inner link by changing its Data–Source from the SmartFrame to the Customer SmartDataObject. There is now a link from the Customer SmartDataObject directly to the Order SmartDataObject, and the two objects can function as if they are in the same container. Note that with a pass-through link, it is the link rather than the data that is passed through.
Note also that the outer link, from the Customer SmartDataObject to the SmartFrame, is maintained. This enables the code in the SmartFrame to use Customer keys passed from the Customer SmartDataObject. There is no standard code in the SmartFrame object or its super procedure
containr.p
to handle the data. If you want, you can write application code to respond to events from the Customer SmartDataObject.
Copyright © 2004 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095 |