The wwBusinessPro data access library supports table-based definitions of the Business Objects used in an application. This also allows you to define Parent-Child relationships between the records and tables in your app.

You can download wwBusinessPro from the project hosted on BitBucket.org.

The default table name for the Business Object definition table is “wwBusinessObjects”.dbf”. Just make sure the Path includes the location of this table, and run the form “wwDictionary.scx” to open and edit the rows in this maintenance form.

Here is a screenshot of the Business Object Dictionary form included in wwBusinessPro:

When using a wwBusProParent, you set properties on the Parent that tell it about the Child class.
Then, the Parent will create the Child class for you.
You do not create the Child when writing your code, let the Parent do that.

You need to create a VCX library and put a Child class for each Child collection in there,
with its Child properties already set up. This allows the Parent to create the Child when he
needs it. If you follow the path of the Get() method, you will see that the Parent creates a
Child class object and attaches it to its oLineItems property. So, once your Child classes are
configured in a VCX, you will not actually have to write any code to access them (unless you are
doing some special case, custom coding), you just set up the Parent so he can find them.
The Parent will handle all that for you, including the fetching of the related Child records.

You can also put your Parent objects in the VCX and set their properties in the VCX file.
This sample code is shown here simply to show which properties are required to make it all work.

*=================================
* == Sample to  show a Parent BO configured to use a String lookup and work with related Child Records
*=================================

Local loSrHead AS ‘cSrHead’

Set ClassLib To MyMainLibrary Additive
Set ClassLib To MyBoLibrary Additive  && Include your Business Object ClassLibrary

loSrHead = CreateObject(‘MyInvoiceBoClass’) &&  A Parent class found in your BO Library VCX

*– These settings are native to the base wwBusiness operation
loSrHead.cFileName = ‘tblSrHead’ && The table name (.dbf file or Sql Server table name)
loSrHead.cAlias = ‘csrSrHead’  &&  Local alias name to use when opening file
loSrHead.nDataMode = 0  && Data access mode for the business object. 0 – Native Fox dbf, 2 – SQL Server
loSrHead.cPKFIeld= ‘PK’    && Points to the unique Key value column in the table. Usually an Integer column.

*– This code section is part of wwBusinessPro feature set wwBusinessPro allows for String-based lookups and related Child cursors…
loSrHead.cLookupField = ‘storeno+docno’  && This is an example of a compound string unique key lookup value.
loSrHead.cAdditionalFilter = ‘mtype = [0]’  && (Optional) Provides a way to further filter the record locating process.
loSrHead.cPKFIeld= ‘storeno+docno’           && Set to same value as cLookupField if no Integer PK is available in the table.

loSrHead.lLoadLineItems = .t. && Tells it load Child records when getting the Parent record.
loSrHead.lAllowEditLineItems = .t.  && Tells it create a ReadWrite cursor when creating the Child record cursor

*– Setup the Child properties on the Parent
loSrHead.cLineItemsClass = ‘cSrItems’  && Child class must exist in the MyBoLibrary.vcx
loSrHead.cLineItemsAlias = ‘curSrItems’ && Cursor name where you want the Child records to be stored

*– Fetch the Parent and create a Child Cursor
loSrHead.Get(‘TWU STORE RN2009100003’) && For String lookups
loSrHead.Get(12345) && For Integer lookups

If loSrHead.lFound = .f.
*– Add any Not Found handling code here
Endif

If loSrHead.nErrorCount > 0
*– Add any Error handling code here, if not already handled in your classes.
Endif

*– Make some changes to the loSeHead.oData object and to the Child cursor
*– and save the changes…
loSrHead.Save(.t.) && .t. Tells it to save changes to the Child records also

One more thing about the Child classes…

When setting up your Child in the VCX, these are the properties you need to set on it:

cFilename (Required. Name of the dbf or Sql Server table)
cAlias (Optional. Will use cFilename by default)
cPKField (Must be an Integer. See “Important Note” below)
cFKField (Must be an Integer. Maps to Parents PK field)
cLookupField (Optional. Maps to Parents cLookupField. Use when Parent uses for String lookups)
cOrderFld (Optional. Can be used to set the ordering of child records. i.e. a sequnce field)

These properties provide the info needed by the LoadLineItems() method work out of the box.
Sometimes you may want to overwrite the LoadLineItems() method with custom code, but the default
should work in basic configurations.

IMPORTANT NOTE:
In order to save changes on the Child records, they need a unique PK that can be used. See cPKField.
String cLookupField works fine to load the records in, but it does not guarantee uniqueness when
trying to save changes back.

Again, you can use cLookupField Stings for loading the records, but you must have Integer PKs
on your Child records to allow saving changes back.

Note: This post if part of a complete series on the West Wind wwBusiness library.
Click here to see the full index

Before we start digging into parent/child data access with wwBusinessPro, let’s have a review of the basics. Suppose we want a Invoice object, and child set of Invoice Line Items that belong to that invoice. This is possible, even simple, with wwBusninessPro. In fact, in this post I’ll also show you how to handle a second child collection, like Invoice Payments, related to the Invoice. If you follow the example shown here, you’ll be able to handle cases where you have a single business objust with MULTIPLE child collections.

For example, here is what a really complex “aggregate” business object can look like. In my main business app, I have one complex business object that loads 4 additional child cursors in addition to the base oLineItems collection, and, it also loads customer and user info into oCustomer and oUser objects that I added onto the BO.

So let’s get started…

Parent and One Child Cursor

Parent class – Create your Invoice class as subclass of wwBusProParent.

At this point, you will see that it has *ONE* child collection object and related properties already built in. The oLineItems object will hold a object reference to the child item class. To make it active (so that it fetches child records every time you fetch a new parent object), you will need to set the cLineItemsClass, cLineItemsAlias, and lLoadtems properties.

The cLineItemsClassproperty points to a lineitems class that you must define in your VCX and it holds the table name of where the child records live and the key field name which links it to the PK on the parent.

The cLineItemsAliasproperty is the name of the cursor that where the child records will live.

Finally, be sure you set the lLoadLineItems property to .t. to make sure the main BO will load the line items each time you call the Get() method on the Parent.

Child Class – Create your InvoiceLineItems child class as a subclass of wwBusProItemList.

Set the properties cFilename and cFKField, which identify the Child table, and the field in the table that links back to the Parent PK in the invoice class.

So that’s it.  You’ve just set up the built-in functionality for the wwBusinessProParent class to handle the Parent BO and its set of child objects.

Need to handle MULTIPLE sets of child records?

Let’s say you also want to fetch all InvoicePayments records every time you load up an Invoice object…

After you’ve configured your “Invoice” and “InvoiceLineItems” classes as described above, and add the following properties and one method to cover the “Payments” collection:

New Properties:

• cPaymentItemsClass
• cPaymentItemsAlias
• lLoadPayments
• lAllowEditPaymentItems (optional, but something I include on my so I can enable or disable stuff in the UI layer)

New Method:

• GetPaymentItems()

Now you need write two simple code blocks:

1. To populate the PaymentItems cursor (in addition to the LineItems cursor) every time you fetch an Invoice, you need to override the LoadRelatedData() method on the Invoice class like this:

2. Define the GetPaymentItems() method like this:

That’s it.

Once you have brought this Invoice object to life, you will have 3 classes in your VCX:

Invoice (based on wwBusProParent)

InvoiceLineItems (based on wwBusProItemList) (this is what the default oLineItems will point to)

InvoicePaymentItems (based on wwBusProItemList) (this is what the above new properties and methods will point to)

When complete, your “Aggregate” Invoice Business Object will look like this:

Invoice

.oLineItems

.oPaymentItems

I know it might seem complicated at first, but once you understand what’s happening, it really not hard.