skip to main content
OpenEdge Development: AppBuilder
Customizing AppBuilder : Creating extended features (XFTRs)
 
Creating extended features (XFTRs)
An XFTR is a code block that you write to customize the behavior of AppBuilder. There are two uses for XFTRs:
*Adding custom run‑time code
*Adding text blocks that will direct your own routines to interact with the user
An XFTR can be self‑modifying; that is, change itself based on user action. Figure 73 shows a sample XFTR.
 
&ANALYZE-SUSPEND _UIB-CODE-BLOCK _XFTR "SmartDataBrowserWizard" bTableWin _INLINE
/* Actions: adm2/support/_wizard.w ? ? ? adm2/support/_wizdel.p */
/* SmartDataBrowser Wizard
Welcome to the SmartDataBrowser Wizard! During the next few steps, the wizard will lead you through creating a SmartDataBrowser object. First you will choose a DataSource to supply data to the SmartDataBrowser, then you can specify the columns that will be displayed in the SmartDataBrowser. Press Next to proceed.
adm2/support/_wizntro.w,adm2/support/_wizds.w,adm2/support/_wizdfld.w,adm2/support/_wizend.w 
*/
/* _UIB-CODE-BLOCK-END */
&ANALYZE-RESUME
Figure 73: XFTR in browser.w template
This code does not, by itself, perform any customized processing. However, it points to other ABL procedures (adm2/support/_wizard.w and adm2/support/_wizdel.p) that do perform customized processing. AppBuilder calls these procedures when significant AppBuilder events occur; for example, when a design window is realized or code is generated. Consequently, these procedures are called XFTR event handlers. An XFTR can reference up to five such procedures for AppBuilder events (see Table 19).
As this example illustrates, an XFTR has five sections:
*An opening &ANALYZE-SUSPEND directive (required)
*A comment that maps event types to event handlers (required)
*A comment that contains code passed to the event handlers (optional)
*A comment that closes the code block (required)
*A closing &ANALYZE-RESUME directive (required)
The sections that follow explain how to set up these sections.
The &ANALYZE-SUSPEND directive for XFTRs
An XFTR code block begins with an &ANALYZE-SUSPEND directive. This directive is required. This is its syntax for XFTR:
 
Syntax 
&ANALYZE-SUSPEND UIB-CODE-BLOCK XFTR name object INLINE
The name value is a quoted string that specifies the name of the XFTR. The object value is an unquoted string with no embedded spaces that specifies a window name; if the procedure file has no window, specify this value as “Procedure”.
The event-mapping comment
This comment maps various AppBuilder events to XFTR event handlers. It is parsed by AppBuilder and must be the first comment after the &ANALYZE-SUSPEND directive. Figure 74 provides an example, and illustrates the components of this comment type.
Figure 74: Event handler components
Components 0 and 7 are standard comment delimiters. Component 1, which must end in a colon, is simply a title for the comment. Components 2 through 6 are space‑delimited procedure names for the XFTR event handlers; each maps to a particular AppBuilder event, as follows:
*Position 2 maps to the Realize event.
*Position 3 maps to the Edit event.
*Position 4 maps to the Destroy event.
*Position 5 maps to the Read event.
*Position 6 maps to the Write event.
For example, in Figure 74, if an AppBuilder Realize event occurs, AppBuilder calls the adm2/support/_wizard.w event. Note that a question mark indicates that no event handler is specified for the corresponding event.
Table 19 summarizes AppBuilder events that you can map to XFTR event handlers.
 
Table 19: AppBuilder events 
AppBuilder event
Description
User actions
Realize
Occurs when a design window is realized.
Opening a procedure file,
creating a new procedure file,
changing layouts, or
changing size of a window
Edit
Occurs when AppBuilder presents an XFTR code block for editing.
Selecting an XFTR code section from the Section Editor’s List Sections dialog box
Destroy
Occurs when a procedure file is closed, or when AppBuilder closes a design window.
Closing a design window
Read
Occurs when AppBuilder has finished opening a procedure file.
Opening a procedure file
Write
Occurs when AppBuilder generates code and saves it to a procedure file. It specifically, occurs when the XFTR is encountered at code generation.
Saving or running a design window
The compilable code comment
This second comment, which is optional, has no specific format. The code section enclosed between the comment delimiters must be a block of AVM‑compilable code (which can include comments). AppBuilder passes the contents of this code section to the XFTR event handlers that you reference in the first comment; the code executes when the procedure file is run.
The ending comment
The third comment simply specifies the end of the code block. Include it exactly as shown:
 
/* _UIB-CODE-BLOCK-END */
The &ANALYZE-RESUME directive for XFTRs
An XFTR code block ends with an &ANALYZE-RESUME directive. Include it exactly as shown:
 
&ANALYZE-RESUME
How AppBuilder runs XFTR event handlers
When a AppBuilder event occurs for a specific procedure file and the procedure file contains an XFTR code block with an XFTR event handler specified in the corresponding position, AppBuilder runs the XFTR event handler and passes it two parameters:
*The context ID (integer) of the XFTR code block (INPUT parameter). A context ID is a unique integer ID for the code block. It can be used by other procedures in AppBuilder’s API.
*The contents (CHARACTER) of the optional code section (the section in between the first and last comments) in the XFTR code block (INPUT-OUTPUT parameter).
Make sure that your XFTR event handler can accept these parameters.