ProMatrix One-To-Many Form Builder

The VPM Enterprise One-To-Many Form Builder is a builder that automates the creation of a form based on the Form_Toolbar_OneToMany form class. Use this builder when you need to create a data maintenance form that maintains data from a parent table, view or CursorAdapter in one page frame and data from child tables, views or CursorAdapters in grids on pages in a second page frame.

Important: The parent of a One-to-Many form may be a table, a view or a CursorAdapter regardless of whether the children are tables, views or CursorAdapters. However, the children must be either (a) all tables or (b) a mixture of views and CursorAdapters. You cannot have a child table with child views and CursorAdapters.

Ø To build a One-to-Many Form

Opening the Form Editor: The following steps assume that you already have opened the Form Editor for the new form you are creating. You can open a Form Editor for a new form by adding a menu option or through the Called Objects list of another Object Editor. If you need help with opening the Form Editor for a new form, see How to Begin Creating a New Application Object.

1. New Form Dialog

Click the Edit button on the Form Editor. VPM Enterprise displays the New Form dialog.

·       Select Form_Toolbar_OneToMany Form Class: With the Blank – Specify Class option button selected, click OK. VPME displays the Select Form Class dialog. Use the dialog to select the Form_Toolbar_OneToMany class in the VPME form class library that you want (either VPMFORMS.VCX, DEVFORMS.VCX or PROFORMS.VCX).

After selecting the Form_Toolbar_OneToMany class, VPME brings up the Visual FoxPro Form Designer with the a Form_Toolbar_OneToMany form displayed.

2. Set Up the Data Environment and Form Properties

1.   Open Data Environment: Click the Form Designer outside the form with your right mouse button. Click the Data Environment option on the popup menu. The Form Designer displays the Data Environment window and the Add Table or View dialog.

2.   Tables and Views: Add all the tables and views you will use on the form to the Data Environment. Set any relations needed.

3.   CursorAdapters: To add a CursorAdapter to the Data Environment:

·       If it’s not already open, open the Data Environment of the form.

·       Right-click on the Data Environment window.

·       Select the Builder option on the right-click menu. Note: If you select the Add CursorAdapter option on the right-click menu, an empty CursorAdapter will be added to the Data Environment that is based on the default VFP CursorAdapter class, which is not what you want.

·       In the DataEnvironment Builder form activate the Cursors page.

·       Click the Add button.

·       In the Open dialog find the class library that contains the CursorAdapter class that you want to add to the Data Environment. Then, select the desired CursorAdapter class and click the OK button.

·       Important: In the CursorAdapter Builder form that comes up, click the Cancel button.

·       The selected CursorAdapter will then appear in the list of CursorAdapters in the DataEnvironment Builder form. Click the OK button and the CursorAdapter will be added to the DE.

    

Note: The parent of a One-to-Many form may be a table, view or CursorAdapter regardless of whether the children are tables, views or CursorAdapter. However, the children must be either (a) all tables or (b) a mixture of views and CursorAdapters. You cannot have a child table with child views and CursorAdapters.

4.   Set Child Table Relations: If you are using child tables for the form, in the Data Environment set the relations from the parent table, view or CursorAdapter to the child tables by dragging the linking field from the parent table, view or CursorAdapter and dropping it on the linking index in the child table. If the parent and child tables are in a DBC with persistent relations already set up, the relations will be set automatically.

Set Child View or CursorAdapter Relations: If you are using child views or CursorAdapters for the form, you cannot set a relation from a parent table, view or CursorAdapter into a child view or CursorAdapter in the Data Environment. Instead, when you create the child view or CursorAdapter, you must create the view or CursorAdapter with a filter that has a name of “ParentPKValue”. This means that you create a Filter on the foreign key field or expression (if the foreign key is compound) that links the child to the parent with the “?ParentPKValue” variable name. See View Filters and CursorAdapter Filters.

Tip - Cursor vs. Table, View or CursorAdapter Name: When the Data Environment window is active, the Visual FoxPro Properties window denotes each table, view or CursorAdapter in the Data Environment as Cursor1, Cursor2, Cursor3, etc. When you select one of the Cursors in the Object box on the Properties Window, the CursorSource property shows you the name of the table, view or CursorAdapter.

5.   Cursor BufferModeOverride Property: For each child table, view or CursorAdapter enable optimistic table buffering by setting the Cursor BufferModeOverride property to “5 - Optimistic table buffering”.

6.   BeforeOpenTables Event: If the form includes a view or CursorAdapter in the Data Environment, add the following two lines of code to the BeforeOpenTables Event of the Data Environment (see Special Steps for Views and CursorAdapters):

   SET TALK OFF
SET DELETED ON

   Matching Remote Views: If you will be using matching remote views with the form, add the following line of code to the BeforeOpenTables event:

   _SCREEN.oApp.LocalToRemote (This)

7.   Order Property for Parent Table: If the parent is a table, set the Order property of the parent cursor if you want to specify the order of the parent table when the form first appears. 

·       cInitialTag Property for Parent View or CursorAdapter: If the parent is a view or CursorAdapter, use the cInitialTag property of the form to specify the order of the parent when the form first appears. In the cInitialTag property of the form enter the Tag Name shown in the Data Builder for the tag definition that you want to use to set the initial order for the parent. If you like, you can also use this property to set the order for a parent table instead of the Order property of the cursor.

8.   Setting the Order for Child Tables: The order of child tables is determined by the ChildOrder property of the relation set from the parent table, view or CursorAdapter to a child table. To set the order of a child table, create an index for the child with an expression that (a) begins with the foreign key field(s) that link the child to the parent and (b) ends with the fields that provide the child table order you want. Then, when you set the ChildOrder property of the relation from the parent to the child, use this index tag.

    Setting the Order for Child Views and CursorAdapters: To use an index tag to set the order for child views and CursorAdapters, add code to the Load method of the form that calls the SetOrder method of the DataHandler object. SetOrder will create the tag if it doesn’t already exist. For example:

   DODEFAULT()
ThisForm.oVPMDataHandler.SetOrder(stcAlias,stcTagName)

   where,

  stcAlias is a character expression that contains the child view or CursorAdapter alias,

stcTagName is a character expression that contains the Tag Name from the tag definition in the Data Builder.

9.   NoDataOnLoad Property - Views: If you are using a parent filtered view, set the parent view's Data Environment cursor NoDataOnLoad property to .T. If you are using child views, set the NoDataOnLoad property to .T. (true) for each child view cursor.

10. NoData Property – CursorAdapters: If you are using a parent filtered CursorAdapter, set the NoData property of the parent CursorAdapter in the Data Environment to .T. If you are using child CursorAdapters, set the NoData property to .T. for each child CursorAdapter cursor.

11. Very Important - InitialSelectedAlias Property: Set the Data Environment InitialSelectedAlias property to the parent table’s, view’s or CursorAdapter’s alias.

12. Private Data Session: If you do not want the form to use a private data session, set the form’s DataSession property to “1”.

13. Find Form: You can choose to display the VPME Standard or SQL Find Form at form startup by setting the form's lStartWithFind property to .T.

14. lSaveNewParentOnNewChild Property: By default, when the New Button next to the child grid is clicked and the parent record is new but not saved, a message is displayed notifying the user that the new parent record should be saved before adding a child record. You can change this default behavior to automatically save the parent record before the new child record is created by setting the form's lSaveNewParentOnNewChild property to .T.

3. Run the ProMatrix One-To-Many Form Builder

1.   Right click on the Form Designer and select Builder from the popup menu. VPM Enterprise displays the Builder Selection dialog.

    

2.   Select ProMatrix One-To-Many Form Builder from the Builder Selection dialog. VPME displays the ProMatrix One-To-Many Form Builder.

    

3.   On the ProMatrix One-To-Many Form Builder enter/select the following items:

·       Form Name: Enter a unique name not used on any other form in the application.

·       Form Caption: Enter the caption that you want to display in the form's title bar.

4. Set Up the Parent Page(s)

When the One-To-Many Form Builder first appears Parent Pages will be selected so that you can set up the form for the parent table, view or CursorAdapter.

Tip: The parent table, view or CursorAdapter is the table, view or CursorAdapter specified in the Data Environment's InitialSelectedAlias property. The form displays data from the parent table, view or CursorAdapter on a page frame at the top of the form.

1.   Select Number of Pages: By default, the One-To-Many Form Builder adds one page to the parent page frame. Click the Add Page button at the bottom of the One-To-Many Form Builder to add additional parent pages.

     If you add a page you don't want, you can remove it by selecting the page and clicking the Remove Page button.

2.   Set Up Each Parent Page: Select each parent page and set up the data to be displayed on the page as described in steps 3 through 5 below.

3.   Page Caption: Enter a caption for the page.

4.   Select Fields: The ProMatrix One-To-Many Form Builder shows the fields from the parent table, view or CursorAdapter on each parent page. Move the fields you want on the page from the Unselected Fields list to the Selected Fields list.

5.   Selected Field Properties: When you highlight a field in the Selected Fields list, the Selected Field Properties box shows:

·       Label Caption: The field Description (Long) property entry from the Data Builder. The Form Builder will put the Label Caption on the page.

Tip: After the form is built, you can change a label on a parent page to something other than the field label text in the Data Builder. To do this, select the label, change it's Caption property to the text you want, and then change the label’s lOverrideCaption property to .T.

·       Control Type: The default VPM Enterprise control class that will be used to put the field on the page. You can change the control class via this Control Type combo box. For example, by default VPM Enterprise puts a numeric field on a form using the TextBox class. You can change the class to the Spinner class through the Control Type combo box.

Tip – Picklist Help: If a field is a foreign key using Referential or Set validation, choose a VPME textbox or combobox control for the field and later set up the control properties to get the Picklist behavior you want.

·       Read-Only: If you want to make the field read-only, check this box.

6.   Repeat Steps 2 to 5 for each parent page.

5. Set Up the Child Pages

Click the Child Grid Pages tab to set up the child pages. The One-to-Many form displays data from the child tables, views and CursorAdapters in grids on pages in a page frame at the bottom of the form.

1.   Select Number of Pages: By default, the One-To-Many Form Builder adds one page to the child page frame. Click the Add Page button at the bottom of the One-To-Many Form Builder to add additional child pages.

   If you add a page you don't want, you can remove it by selecting the page and clicking the Remove Page button.

2.   Set Up Each Child Page: Select each child page and set up the data to be displayed on the page as described in steps 3 through 6 below.

3.   Page Caption: Enter a caption for the page.

4.   Select the Child Table: In the Child Table combo box, select the name of the table, view or CursorAdapter to be displayed in a grid on the page.

Tip: The children must be either (a) all tables or (b) a mixture of views and CursorAdapters. You cannot have a child table with child views and CursorAdapters.

5.   Select Fields: The ProMatrix One-To-Many Form Builder shows the fields from the child table, view or CursorAdapter selected on each child page. Move the fields you want on the page from the Unselected Fields list to the Selected Fields list.

6.   Selected Field Properties: When you highlight a field in the Selected Fields list, the Selected Field Properties box shows:

·       Header Caption: The field Description (Short) property entry from the Data Builder. The OTM Form Builder will put a field’s Description (Short) entry in the field’s grid Header Caption.

Tip: After the form is built, you can change a header caption on a grid column to something other than the field Description (Short) entry in the Data Builder. To do this, select the Header object in the Property window and change it's Caption property to the text you want. Then, set the lGridOverrideCaption property of the field’s control in the grid to .T. (true).

Tip: If you want to override the Data Builder field Description (Short) entries of all fields in the grid, set the grid’s lGridOverrideCaption property to .T. Then, enter the header captions you want in each field’s Header Caption property.

·       Read-Only: If you want to make the grid column read-only, check this box.

7.   Repeat Steps 2 to 6 for each child page.

6. Build Form

After you have set up the parent and child pages as you want them, click the Build Form button. The ProMatrix One-To-Many Form Builder will build the form for you. The form will look something like this:

7. Clean Up

After the One-To-Many Form Builder creates the form, you will want to clean it up. In particular, you will need to resize the child grid columns if the grid column header is much longer than the field displayed in the column. You may also need to change the relative sizes of the parent and child page frames.

8. Complete Standard Form Tasks

1.   Run the ProMatrix Toolbar List Builder: Run the ProMatrix Toolbar List Builder to create a customized toolbar List control grid for the form. See ProMatrix Toolbar List Builder.

2.   Run the ProMatrix Condition Field List Builder: Run the ProMatrix Condition Field List Builder to select the fields that will appear in the form’s Condition Builder Field list. See ProMatrix Condition Field List Builder.

3.   Set the Tab Order: Set the tab order of the form through the Tab Order option on the View menu.

 

More:

ProMatrix Related Pages Form Builder