How to Use the Related Pages Form Builder

The following steps show you how to use the ProMatrix Related Pages Form Builder to build Related Pages forms based on the Form_Toolbar_RelatedPages class.

Opening the Form Editor: These 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.

1. New Form Dialog

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

·       Select Form_Toolbar_RelatedPages 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_RelatedPages class in the VPME form class library that you want (either VPMFORMS.VCX, DEVFORMS.VCX or PROFORMS.VCX).

After selecting the Form_Toolbar_RelatedPages class, VPME brings up the Visual FoxPro Form Designer with the a Form_Toolbar_RelatedPages 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 Related Pages form parent may be a table or a view regardless of whether the children, grandchildren, etc. are tables or views. 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, etc. tables for the form, in the Data Environment set the relations from the parent table, view or CursorAdapter to the child, etc. 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, etc. tables are in a DBC with persistent relations already set up, the relations will be set automatically.

Tip – Toolbar List Control & Linking Index Expression for Tables: The Toolbar List control for a child, etc. table on a Related Pages form is automatically populated with the fields in the table’s index that you use to link the table to its parent in the Data Environment for the form. Therefore, you should create a linking index tag expression that begins with the child table foreign key field(s) that link the table to its parent followed by whatever fields you want to appear in the child page’s Toolbar List control.

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 - Toolbar List Control for Views and CursorAdapters: The Toolbar List control for a child, etc. view or CursorAdapter on a Related Pages form is automatically populated with the fields in the index tag definition that you use with the SetOrder method of the DataHandler object to set the order for the view or CursorAdapter. (See step 8 below.) If you don’t use the SetOrder method to set the order for the view or CursorAdapter, the Toolbar List control is populated with the fields in the view’s or CursorAdapter’s primary key tag definition. If you don’t identify a primary key tag definition for the view or CursorAdapter in the Data Builder, the Toolbar List control is populated with the fields in the view’s or CursorAdapter’s foreign key tag definition that you identify when you set up Referential validation on the view’s or CursorAdapter’s foreign key field(s) that links it to its parent for the Related Pages form.

 

Tip: You can customize the Toolbar List control for tables, views and CursorAdapters on a Related Pages form. To learn how, see How can I customize the Toolbar List Grid for cursors on a Related Pages form?.

 

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.

 

Tip - Relation Name: When the Data Environment window is active, the Visual FoxPro Properties window denotes each relation in the Data Environment as Relation1, Relation2, Relation3, etc.

Tip – Relation Names: Do not change the default relation names that Visual FoxPro assigns to relations when using the VPM Enterprise Related Pages Form Builder. If you change the names from Relation1, Relation2, Relation3, etc., your Related Pages form will not run properly

5.   Cursor BufferModeOverride Property: For each table, view or CursorAdapter that will be displayed on a page with an Editable Grid 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 Topmost Parent Table: If the Topmost 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 Topmost Parent View or CursorAdapter: If the Topmost Parent is a view or CursorAdapter, use the cInitialTag property of the form to specify the order of the parent view or CursorAdapter when the form first appears. In the cInitialTag property of the form enter the Tag Name as shown in the Data Builder for the tag definition that you want to use to set the initial order for the parent view or CursorAdapter. 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, etc. 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 filtered view, set the view's Data Environment cursor NoDataOnLoad property to .T. If you are using child, etc. views, set the NoDataOnLoad property to .T. (true) for each child, etc. view cursor.

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

11. Very Important - InitialSelectedAlias Property: Set the Data Environment InitialSelectedAlias property to the Topmost 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.

3. Run the ProMatrix Related Pages 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 Related Pages Form Builder from the Builder Selection dialog. VPM Enterprise displays the ProMatrix Related Pages Form Builder.

    

3.   On the ProMatrix Related Pages 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 Page(s)

When the Related Pages Form Builder first appears, the alias of the Topmost Parent table, view or CursorAdapter is shown in the Update Table box so that you can set up the first page for the Topmost Parent table, view or CursorAdapter. Normally, you will want to edit the Topmost Parent table, view or CursorAdapter on the first page in the pageframe. The Topmost Parent table, view or CursorAdapter is the table, view or CursorAdapter in the Data Environment's InitialSelectedAlias property.

1.   Select the Number of Pages: By default, the Related Pages Form Builder adds one page to the pageframe. Click the Add Page button at the bottom of the Related Pages Form Builder to add additional 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 Page: Select each page and set up the data to be displayed on the page as described in steps 3 through 9.

3.   Grid: If you want to display data on a page in an Editable Grid, check the Grid check box.

4.   Update Table: Select the table, view or CursorAdapter from the Data Environment to edit on the page.

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

6.   Select Fields: The ProMatrix Related Pages Form Builder shows the fields from all the tables, views and CursorAdapters in the Data Environment in the Unselected Fields list. Move the fields you want on the page from the Unselected Fields list to the Selected Fields list. Normally, you will only select fields from the table, view or CursorAdapter you selected in the Update Table box. Be sure to look at the table, view or CursorAdapter alias before selecting a field.

·       Order Fields: The fields in the Selected Fields list will be placed on the page or in the grid in the order they are listed. Therefore, change the order of the fields so that the order meets your specifications.

7.   Selected Field Properties for Non-Grid Pages: When you highlight a field in the Selected Fields list, the Selected Field Properties box shows the following if you did not check the Grid check box:

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

Tip: After the form is built, you can change a label on a page to something other than the field Label Caption 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.

8.   Selected Field Properties for Grid Pages: When you highlight a field in the Selected Fields list, the Selected Field Properties box shows:

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

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.

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

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

9.   Calculated Fields for Grids: The ProMatrix Related Pages Builder allows you to easily create calculated fields for a grid. To create a calculated field for a grid column:

·       Click the Calc button at the bottom of the column of buttons on the Builder. The Builder displays the Visual FoxPro Expression Builder.

·       Create your calculation expression in the Expression Builder. When you close the Expression Builder, the calculation expression will be added to the Selected Fields list with the prefix “Calc:”.

·       Set up the Selected Field Properties for the calculated field as described in step 8 above.

·       You can edit a calculated field by selecting the field in the Selected Fields list and clicking the Calc button.

5. Build Form

After you have set up the pages as you want them, click the Build Form button. The ProMatrix Related Pages Form Builder will build the form for you.

6. Clean Up

After the Related Pages Form Builder creates the form, you will want to clean it up. In particular, you will need to resize grid columns if a grid column header is much longer than the field displayed in the column.

7. 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.

Tip – GetConditionPageNumber Method: By default, if more than one page of a Related Pages pageframe displays data from the same cursor, any conditions that are created in the Condition Builder (Filter, Group Delete, or Locate) are shown only for the page for which the Condition Builder was brought up. The GetConditionPageNumber method of the Form_Toolbar class allows the Condition Builder to show the same list of conditions for each page that uses a common cursor. It also allows those pages to share the same fields list defined in the Condition Field List Builder.  To learn more, refer to the VPME 9.1 Technical Reference manual’s description of the Form_Toolbar class GetConditionPageNumber method and look at the comments for an example of how this method can be used.

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

 

 

 

More:

ProMatrix Grid Builder - an Editable Grid