Linked Form Support in VFE

In my last blog entry I mentioned that we've added support for a new feature named "Linked Forms" to our Visual FoxExpress framework. Linked forms allows the developer to specify a form that's linked to a field or a view parameter. A linked form is specified by setting the "Linked Form Class Name" for the field or view parameter in the data dictionary.

When a field or view parameter has a linked form associated with it the label appears as a hyperlink. If the user clicks the label, the form object is created and a reference to the label is passed to the form's init method. If the form that contains the label has a DoChildForm method, then the linked form is creating using the DoChildForm method. If there isn't a DoChildForm method available then the Application Object's DoForm method is executed.

That's pretty much all this feature does out of the box. What happens in the linked form from there is up to the developer. There are a number of possibilities.

In some scenarios you may opt to do nothing in a linked form when it's called. If you're building your application using local tables and the table used by the linked form is open in the calling form's data session, the record pointer should already be position on correct record when the linked form is opened. If you're using the linked form as some type of lookup, perhaps you'd wait to have the user file in parameter values and then act when a record is selected.

A more common scenario will be to attempt to move to the data associated with the value of the field the linked form is tied to. Remember when the linked form is called an object reference to the label that made the call is passed. From that label, you can easily retrieve data or other properties and act on them. Here's some sample code that sets a parameter based on the label passed to the form and requeries:

*==============================================================================
* Method:      Init
* Purpose:      If a parameter is passed, search for a customer that matches
*          it.
* Author:      F1 Technologies
* Parameters:    toParameter, Object, in this case a label object from the
*          calling form.
* Returns:      None
* Added:      02/01/2006
*==============================================================================
LPARAMETERS ;
 toParameter

IF PCOUNT() = 1
 This.oPresentObj.oBizObj.Search(toParameter.oField.Name, toParameter.oField.Value)
ENDIF
DODEFAULT(toParameter)

* Clear the object reference held in the parameter so we don't have a reference
* to an object in another form hanging around.
This.oParameter = NULL

This example works with a form that is based on a small view that will have already retrieved all of its data automatically by the time the form's init method is called, so all we do here is call the business object's search method to position the record pointer on the appropriate record. If we were working with parameterized data we could've just as easily set a parameter and then requeried.

The most important line in the example is This.oParameter = NULL. By default, when a parameter is passed to a form the parameter is stored in the form's oParameter property. In the case of linked forms, this will be an object reference to a control in another form. This object should reference should always be nullified before the form is destroyed. If you're using a non-modal form, as I was in this example, it's more or less required to release this reference at or near the end of the Init method. If this object reference is left in place and the calling form is subsequently released VFP isn't very happy about it and eventually it will let you know in the form of a crash. If the Linked Form is modal the framework takes care of clearing the oParameter property when the form is destroyed, but it is probably still best to take a cautious approach to this and release the object reference as soon as its no longer needed.

This was a relatively easy feature to implement, but it can be quite powerful. I'm making use of it in several places in the new sample application and someday in the near future we'll actually make that available. In the meantime, give it a whirl. It's pretty straightforward.