This chapter contains the following topics:
A subform is a control designed for use on a power form or another subform. Although technically a control, subforms have some form characteristics as well. Each subform represents one data view; that is, each subform control can have a single business view (BV) attached to it. Power forms can contain several subforms, so a single power form with multiple subforms enables users to see multiple data views. For example, a user selecting a purchase order in a grid could see related shipping information in one subform and fulfillment information in another subform on the same power form. When the user selects a row in the grid, all of the data is updated and, most importantly, the user does not have to open a new form to see the updated data.
Together, power forms and subforms provide developers with the ability to code:
Multiple views on a form.
Multiple grids on a form.
Multiple tab controls on a form.
Tab pages with their own business view.
BVs that can communicate with each other, and even react to selection and data changes that occur in other views on the form.
Subforms have two main characteristics:
To its parent, it is a control.
To the controls that it contains, it is a form.
When you place subforms on a power form or subform, the system treats the interactions among them as parent/child relationships, with the power form or subform as the parent and the subforms as the children of the power form and siblings to each other. This hierarchical relationship governs logical relationships. It is also represented visually in the Form Design Aid (FDA) Application Tree View as a hierarchy to help you understand the relationships.
Similarly to a form, a subform owns the data flows between the interface view and the database, including browse, insert, update, or delete. In fact, you create a subform as if it were a form, and then place it as a control. Do not let its appearance fool you, however. A subform is really a control and the FDA interface treats it accordingly. For example, if subform B is contained in power form A, when you select B, the FDA control bar still displays the title of A. Additionally, if you view the data structure, you will see the data structure for A and not for B.
This list describes many of the conditions and factors that you should take into account while designing the subform in FDA:
Subforms have their own BVs (only one per subform), grids, and filters that pass logic between other subforms.
Subforms can be used as tab pages, or they can be placed on a tab page.
Multiple tab controls are permitted unless the subform is inside a tab page.
If the subform is inside a tab page, it cannot have tab controls. However, this restriction cannot be enforced programmatically when you reuse subforms. Therefore, when developing reusable subforms, carefully consider the context in which you expect to use them to prevent poor user interface design.
Toolbar and form/row exits are not permitted on a subform.
Subforms do not contain scroll bars; you must display all controls within the form.
You can add action buttons (Cancel, OK, and so forth) to a subform.
No default action buttons are defined by FDA. Default actions can be placed anywhere on the subform. For example, the default action, Save, can be placed beneath the grid. Use the dotted lines at the top and bottom of a subform during design time as guides for where to place more common default actions. For example, buttons such as Select or Find belong at the top of the form while buttons such as Save or Cancel belong at the bottom.
You can define ER that fires when the user sets or removes focus from the subform, using the Enter Focus and Leave Focus subform events.
After designing the subform, you must return to the parent form and map the parent data fields to the child so that the two can share data as you intend. After associating a data structure with the parent, use the Mapping Links property to establish the data mapping between the parent and subform.
Note:
Because subforms can act as parents, they have the Mapping Links property. However, you can only create mappings on the parent level. If you cannot find the child subform in the Link To field, then you might have mistakenly entered the data mapping property for the child instead of the parent.These property values are significant for subforms:
Show Subform Header
This property enables you to hide or show the title bar of the subform. You must show the header if you want to make the subform collapsible (with the Collapsable property).
Collapsable
This property determines whether the user can choose to view just the title bar (header) of the subform. The ability to collapse subforms is useful on forms that contain a large number of subforms. You must show the header (with the Show Header property) if you want to make the subform collapsible.
Transaction
This property determines where the subform falls within the transaction boundary for the form as a whole.
Additionally, subforms support the form-level properties: Update on Businessview and Fetch on Businessview.
Finally, to enhance reuse, you can associate any number of functions with a subform at design time. Then, during runtime, the parent of the subform can invoke any of those functions with the Call Function system function.
These events can fire on the subform during runtime:
Notified by Child
Notified by Parent
Enter Focus
Leave Focus
Tab Page is Initialized
Tab Page is Selected
Row Is Selected
Grid Record is Fetched
Write Grid Line-Before
Write Grid Line-After
Row Is Unselected
Last Grid Record Has Been Read
Add Record to DB - Before
Add Record to DB - After
Update Record to DB - Before
Update Record to DB - After
Post Commit
Notified by Child and Notified by Parent fire when the child sends data to the parent and vice versa, respectively. Use the Notified by Parent event to run any business logic that you want the application to execute after the parent of the subform calls the Notify Child system function. This logic is usually based on the information passed to this subform from its parent. Use the Notified by Child event to run any business logic that you want the application to execute after its child calls the Notify Parent system function. This logic is usually based on the information returned from its child. Enter Focus enables you to run ER when the user sets the focus to a subform by entering that subform with a tab or a mouse click. You can useLeave Focus to run ER when the user sets the focus outside of a subform by leaving that subform with a tab or a mouse click.
In addition, a number of events that start with WIZARD can fire on this control as well, but only when on a wizard form.
See Also:
You use subforms to browse or update records using one BV; you cannot place more than one BV on a subform. Subforms can contain most FDA controls (with the notable exception of the parent child control) and may or may not have a grid.
This section discusses how runtime processes the subform control.
Each subform ultimately resides on a parent power form. When the power form initializes, all of its subforms (including the child subforms of its subforms) are initialized. First, runtime initializes these objects in order:
Business view columns (BC).
Subform controls.
Static text.
Helps.
Event rules (ER) structures.
Runtime begins detail data selection and sequencing if the grid option Automatically Find On Entry is enabled.
Subforms do not have a tool bar; instead, you must add push buttons to perform "standard" functions. The push buttons behave the same as the standard push buttons for other form types.
If a subform is on a power browse form, these push buttons are available:
Select
Find
If a subform is on a power edit form, these push buttons are available:
Clear
Find
Delete
Save
Find is a standard push button that is available on all subforms. When the user clicks it, runtime fires the Button Clicked event. If no errors exist in the filter fields, runtime performs data selection and sequencing for the grid or other control if no grid is present. If one or more records are fetched, then runtime loads the control, and sets the mode to Update. If no records were fetched and a grid is present, runtime sets the mode to Add. Then runtime fires the Post Button Clicked event.
Select is a standard push button that is available on subforms placed on power browse forms. When clicked, runtime performs these actions:
Load the mapping link value from the subform parent.
Fire Button Clicked.
Fire Post Button Clicked.
Clear is a standard push button that is available on subforms placed on power edit forms. When clicked, runtime performs these actions:
Fire Button Clicked.
Clear all controls on the subform.
Clear errors on the subform.
Fire Post Button Clicked.
Delete is a standard push button that is available on all subforms placed on power edit forms. The actual delete from the database does not occur at this point. Runtime verifies the intention to delete when the user clicks the Delete button, and then commits the deletion when the user clicks the Save button. Consequently, if the user clicks the Cancel button, the records are not purged from the database.
Save is a standard push button that is available on all subforms placed on power edit forms. It validates the information on the subform and updates or adds to the database.
Note:
If the subform contains a grid control, the save button processing behaves similarly to the OK button on a headerless/detail form. If the subform does not contain a grid, the Save button processing behaves similarly to the OK button on a fix/inspect form.This section provides an overview of subform creation, and discusses how to:
Create a subform without a power form.
Crete a subform on a power form.
Create a subform as a tab page.
You can create a subform in one of two ways: without a power form, or as a control either directly on a power form or on the tab page of a power form. These two options give you the flexibility to code subforms and power forms independently to accommodate different design schedules. Therefore, you might choose to create a subform outside of the context of a power form if the power form itself is not ready yet or if your group is responsible only for creating a subform that other groups will use on their power forms, for example. Furthermore, you can only create browse subforms directly on a power form, so if you want to create an edit subform, you must create it independently of a given power form.
No matter how you create the subform, it exists as its own entity in the system. Therefore, you can find and insert any subform onto any power form.
When you create it, a blue hashed line appears at the top and bottom of a subform. Use these lines as guides for button placement. Place initial actions, such as find, at the top.
Place concluding actions, such as save, near the bottom. Controls may only exist within the boundary of the subform; you cannot size the subform to be smaller than the area where its child controls reside. This restriction includes hidden controls, so if FDA does not permit you to shrink a subform, ensure that you have no hidden controls preventing the resize.
To create a subform without a power form:
In FDA, select a subform type (reusable browse or reusable edit) from the Form menu under Create.
On Subform Properties, configure the properties for the subform.
Note:
When you save the subform, you are actually creating an application to contain the subform. Keep that in mind when you later insert an alias to the subform on a power form. When you search for the subform, you must first search for the application that contains the subform, and then you can select the subform itself.To create a subform on a power form:
In FDA, open the power form that you want to use to contain the subform.
If you want to insert the subform on a tab page, click the tab control to insert into.
Select Subform from the Insert menu.
On Subform Properties, configure the properties for the subform.
If you are inserting the subform directly on the power form (and not on a tab page), click to place the subform where you want it on the power form (as you would any other control).
If you later change your mind, you can always drag the subform from a tab page to the main power form or vice versa.
To create a subform as a tab page:
In FDA, open the form to which you want to add tab pages.
Add a tab page to the form.
Select the tab page and select Subform or Subform Alias from the Insert menu.
Alternatively, drag a subform from another position on the parent form and drop it on the tab page.
This chapter provides an overview of subform reuse and discusses how to reuse a subform on a power form.
Subforms can exist as discrete objects in the system. You can place the subform itself on a power form; this action is referred to as embedding. You can also reference an existing subform on a power form with an alias; this action is referred to as reusing. Typically, developers reuse subforms that are designed to appear on numerous forms, such as the display of address book information. In this way, you can more easily standardize the interface.
A reused subform is actually just a pointer; therefore, it is unaware of its parent and children in any given context. If you want a reused subform to communicate with its parent or children, you must do so through ER. While you cannot embed a subform within another subform, you can reuse a subform within another subform. In other words, you can embed or reuse a subform within a reusable subform, but you cannot embed or reuse a subform within an embedded subform.
Inserting reusable subforms in a form is different from inserting an embedded subform. They exist as two different control types in the user interface. Therefore, the FDA Menu/Toolbars contain two different insert actions. If you insert an alias, you are prompted for the application. If you insert a reusable subform, you are prompted for the subform. You cannot insert a subform onto a form until the application the subform has been defined in has been saved.
To make reusing subforms effective, you must plan carefully and be cautious when altering subforms. For example, if both a parent and a child are reused, then you must set up their data mappings in a way that facilitates their passing information to each other. You should use variables as often as possible, especially for business view columns (BCs), grid columns (GCs), and form controls (FCs). Establish a naming convention for the variables so that you can determine which ones were created for the purpose of mapping. That way, if another developer wants to reuse the subform and sees several "extra" variables, that developer will understand that the variables are not extraneous.
Knowing that any subform can be reused, you must be careful when changing a subform, even just resizing it. Anyone who is currently pointing to the subform will see the changes you make. It is possible that if you make the subform a little larger that it will no longer fit on someone else's form. Even worse, if you change the data structure by removing elements from it, you might break someone else's application.
Note:
Always determine the full effect of changing a subform, especially its data structure. If you reuse subforms in the applications, check them occasionally to ensure that the subforms have not been altered in such a way as to negatively affect the applications.To insert (reuse) a subform on a power form:
In FDA, open the power form that you want to use to contain the subform.
If you want to insert the subform on a tab page, click the tab control to insert into.
Select Subform Alias from the Insert menu.
On Work with Applications, select the application containing the subform you want to insert.
On Work with Subforms, select the subform you want to insert.
The system inserts an alias to the subform on the power form or tab page.
Note:
Always determine the full effect of changing a subform. If you reuse subforms in the applications, check them occasionally to ensure that the subforms have not been altered in such a way as to negatively affect the applications.Subforms are self-contained; the elements within it cannot be accessed by other subforms or the form. Therefore, to communicate with each other, each subform must present an interface that can be used to pass data into and out of the subform. The interface is presented as a data structure and performs similarly to form and report interconnects. When developing event rules, the data structure items will appear as variable type subform interconnection (SI).
To map parent variables to a child subform:
Select the parent and select Form Properties from the Form menu.
Click the Mapping Link tab.
In the Link To field, select the child subform to which you want to map data.
You cannot map to a grandchild.
Select an element of the child interface and map a variable to it.
Note:
Changing the parent assignment after mapping links have been set or event rules have been developed could cause the application to fail.To enhance reuse, you can associate any number of functions with a subform at design time. Then, during runtime, the parent of the subform can invoke any of those functions with the Call Function system function.
To add a function to a subform:
Click the subform to which you want to add the function and select Form, Create, Function .
The Application Tree View browser switches to the Logical Hierarchy view, and the function appears in the tree as a child object of the subform. (Functions do not appear in the tree if set to the Physical Hierarchy view.)
Right-click the function in the tree and select Edit ER.
The Event Rules Design form appears.
Create the logic for the function as you would for an ER.
This section describes the system function unique to subforms.
This system function enables the parent to invoke any of the functions on any of its children.
Input, required. The subform to affect.
Input, required. The function to invoke. Set the parameter to an applicable object from the object list.Working with Functions and Subforms
This system function makes the subform unavailable for user entry and system use. You cannot invoke functions on a disabled subform.
This system function hides the subform from the user, although the system can still access it. For example, you can invoke functions on a hidden subform.
This system function causes the data in the data structure to be distributed appropriately. It has no parameters.
This system function returns the number of errors that are set on a subform, including its children, if desired.
Input, required. The subform FC to affect. If the subform has children, you can include the errors set on them in the count as well.
Input, required. The object to which to assign the return value. Set the parameter to an applicable object from the object list.
This system function returns the number of warnings that are set on a subform, including its children, if desired.
Input, required. The subform FC to affect. If the subform has children, you can include the warnings set on them in the count as well.
Input, required. The object to which to assign the return value. Set the parameter to an applicable object from the object list.
This system function acquires the ID of the child subform relative to the current form.
Input, required. The object to which to assign the return value. Set the parameter to an applicable object from the object list.
This system function enables you to "push a button" on a subform programmatically.
This system function expands a subform if it is currently collapsed. It has no effect if the Collapsable property is disabled.