SuperInvoice 4.1 - by BoxSoft Development

by Tom Hebenstreit, Review Editor

Published 1999-02-01    Printer-friendly version

SuperInvoice is a template set from BoxSoft Development which has been around in one form or another for quite a long time. Recently, BoxSoft released version 4 of these templates as an add-on to the ABC templates first introduced in Clarion 4 (and refined in Clarion 5). This new version takes full advantage of the ABC class libraries, and because of that, can only be used with ABC based apps and/or programs.

Note: BoxSoft also has a version of SuperInvoice (designated v2.5) for the Clarion legacy templates that has the same basic feature set as the ABC version under review here. The primary differences stem from v4.1’s use of the new built-in ABC Edit In Place (EIP) classes, whereas the older version had to create much of its own EIP code and logic. In general, though, the same concepts hold true for both products. Contact BoxSoft if you have specific questions about the older version.

The problem to be solved

The templates provided by TopSpeed have always had a rather glaring problem when you tried to implement a fairly common scenario – namely, to have a single form which coherently updates both a parent file and a number of child file records. The most common example of this is an Invoice, where you have a parent file (the Invoice header) and a child file containing the individual Items that were sold on the invoice.

But why do I stress ‘coherently’?

Simple. Using the standard templates, you can easily create that type of parent/child update form simply by placing a browse box (with update buttons) for the child file on your parent file update form. Where it all falls to pieces is that the standard templates regard updates to the child file as separate from the update that is occurring to the parent file. In other words, you can call up an update form for the parent (an Invoice, for example), make some changes to it, make some changes to the child records (Line Items for the Invoice) and then discard the changes to the parent using the Cancel button.

The child file changes, however, are NOT canceled. They were independent updates upon the child file, each one added, updated or deleted as if they were being updated via a standard browse, which, in fact, is what is actually happening. The browse just happens to be sitting on a form, that’s all.

What about using Logout and Commit, you say? Why not just initiate a Logout when the parent form is entered and then Commit or Rollback depending on whether the OK or Cancel button is pressed? Well, the problem there is that, for most file systems, a Logout will lock all of the files in question for the duration of the transaction. This means that no other updates can be performed upon any of the files involved until the Commit or Rollback occurs. Not an ideal situation by any means if you are working in a multi-user environment (especially if the person entering the new Invoice record takes twenty minutes to do it!).

A better approach would be to capture the state of all of the child records (the Line Items) when the Invoice is first loaded. That way, you could always update each of the child records and restore the original contents if the user cancels. But what about new Items? Deleted Items? As you can imagine, this can get pretty complicated in short order, as well as involving a fair amount of file I/O. What to do, then, what to do…

The SuperInvoice solution

BoxSoft created SuperInvoice specifically to deal with this type of situation. Their solution to this problem is to keep the entire group of child items (and all updates to them) in a memory queue while the parent record is being edited.

Existing child records are loaded into the queue when the parent form is first opened. New records are added to the queue, not the file. All child updates are performed upon the queue, and only committed to their respective files when the OK (save) button is pressed on the parent form. If the user presses Cancel instead, all that happens is that the contents of the queue are discarded. Even better, since there was no child file I/O and no rollbacks, this means fast response for the user. Clean and simple.

Even though I’ve used an Invoice as my example so far, BoxSoft stresses in the documentation that SuperInvoice is not by any means limited to the Invoice/Line Item paradigm. For example, you can have multiple SuperInvoice templates on a form, making it simple to create, say, a Contact Manager form which allows for multiple phone numbers and multiple email addresses via child files. SuperInvoice will transparently handle all of the logic required to either update or discard changes to both child files (Phone and Email) in one fell swoop. And remember, because the entire transaction was being held in memory, cancelled updates have NO impact on your data files (unless the basic form was auto-incrementing, of course). No rollbacks or other special measures are needed since no physical records are written during these ‘update’ transactions.

As a bonus, SuperInvoice offers the option of wrapping the physical updates to the files within a Logout/Commit transaction. Since the entire update (parent AND children) takes place just as fast as your computer (and/or network) can process it, your transaction times are kept to the absolute minimum.

You can also disable transaction processing entirely. Why would you ever want to do this, you ask? Well, perhaps you need to update files which use different drivers (a no-no in transaction processing). It’s just nice to have the choice.

But wait, there’s more…

So what does SuperInvoice do for you besides cleanly handling those pesky Parent – Child file updates (as if that wasn’t enough)?

Primarily, Super Invoice extends and enriches the basic ABC EIP classes to make them simultaneously more powerful and easier to use. Not a bad trick, if you can pull it off!

Additionally, SuperInvoice allows you to have an update ‘form’ for the queued child items in addition to (or in place of) the EIP functions. This is especially handy if, for example, the child record has more fields that can comfortably be fit within the single line EIP concept. It can also be used to supplement EIP by providing a way to update child file fields that cannot be updated via EIP (like a memo/text box). I say ‘form’, because what it really is is a window type procedure (not a form) with a special SuperInvoice ‘Save’ button template. The save button template mimics the functionality of the standard save to disk type button in that it initiates field validation and saves the update, only it saves it back to the SuperInvoice queue, not the disk.

Sound appealing? Let’s see what it’s actually like to work with.

Installation

I obtained SuperInvoice 4 as a single file install package, downloaded directly from the BoxSoft web site. Note that SuperInvoice 4 supports both Clarion4 and Clarion 5 ABC, so the same package is used for installing for either product.

Upon running the file, I was presented with a number of welcome and information screens, following by a dialog where I could choose the installation directory. The installer did not auto-detect my Clarion directory, so I had to specify that it was on a drive other than C: (the default). Rather annoyingly, when I chose my E:, it presented me with a new install path which was below what happened to be that drive’s current directory. In other words, C:\Clarion4 became E:\CSTools\Clarion4. Not exactly where I wanted it to install. After selecting \Clarion5 as my install directory, it now presented a default of E:\Clarion5\Clarion4. Doh!

After manually editing the install line to make it simply E:\Clarion5, the install proceeded smoothly. Entering the required password was no problem, and the installer offered to add the SUPER directories to my RED (Clarion IDE Redirection) file, which is a nice touch. After a reminder to register the templates, it displayed the Help file to assist in getting familiar with the product. As with all BoxSoft products, it includes an emphatic RTFM (Read the Fine Manuals) notice – and I heartily concur. A few minutes spent perusing the Help file at the beginning makes the entire process of using Super Invoice much easier.

As a side note, this installer was created with the WISE Installation System and I have noticed this annoying behavior with selecting paths in previous versions of WISE, so I can’t strictly blame BoxSoft. Also, if you are installing to C:\Clarion4, you can just accept the default and you’ll never see this problem.

Late update: After this section was written, BoxSoft released an update to SuperInvoice (v4.1). The new installer correctly found my Clarion 5 installation on my E:, using it for the default. Much better, but WISE still exhibits the same quirks if you try to change the install path.

Implementation

Amazingly enough, SuperInvoice is the rare product that doesn’t require adding a global extension template before you can use it. You can just pick a form and go to it, as all of the logic is contained in the SuperInvoice control templates.

This does bring up the first point to keep in mind. SuperInvoice is designed to be used on a form procedure, and, indeed, cannot be placed on a window that doesn’t have an ABC SaveButton (write records to disk) template already on it. Since this template is populated by default as the ‘OK’ button on form procedures, you normally won’t even think about this requirement.

The second requirement before SuperInvoice can be used is that the Parent and Child files must be related in the application’s Dictionary. As this is pretty much standard practice, this is also a painless requirement.

The third requirement is that you need to adjust your thinking (and embed code writing) to reflect the fact that most all SuperInvoice embeds are dealing with records from the queue, not your file. As the documentation repeatedly points out, you can’t just do this:

IF Itm:Quantity=0 THEN RETURN Level:Notify.

Instead, you must prefix the field with the identifier of the Super Invoice object and queue identifier like this:

IF INV3.Q.Itm:Quantity=0 THEN RETURN Level:Notify.

And how do you know the name of the object? Look on the ‘Classes’ tab for the SuperInvoice template. By default it is ‘INV’, with a number to distinguish it from other instances of the Super Invoice object. You can change it to anything you want, though, as long as it is unique.

For those new to the ABC way of doing things, the SuperInvoice documentation is thorough about listing the embed points which you would use to customize or extend the code generated by SuperInvoice. Sample code is provided so that you see just what you should put in those embeds, as well. For example, you are reminded that you can’t just CYCLE out of ABC methods like you could in the legacy templates field accepted embeds (you do a ‘Return Level:Notify’ as shown above).

Activating SuperInvoice on a form is pretty much a matter of dropping on the SuperInvoice ‘InvoiceControl’ control template and filling in template prompts. Here is what the ‘General’ options tab looks like:

‘General’ options.)

SuperInvoice provides a wealth of options to tailor exactly how the list box EIP will behave, and what happens when the user presses various keys. They include:

1. Changing the colors of the selected row (the normal dark blue can be hard on the eyes when editing)
2. Controlling the user’s ability to edit a row (make some rows conditionally disabled)
3. Transaction options, including adding other files to the transaction (an Inventory file which is adjusted by Orders, for example).
4. Options for dealing with adding or deleting rows (automatically adding new rows, priming fields, confirming deletes, etc.)
5. Options for dealing with empty rows (adding them, deleting them, allowing the user to exit with no rows).
6. Navigation options, e.g., what happens when you press the down key, up key, tab key, etc. Do you remain in edit? Do you stay in the same column? And so on…
7. All the usual icon, color and totaling options (as well as a new running balance option). And keep in mind that totals are being done on a queue, not a file, so they are fast.

Basically, if you like the standard ABC EIP options, you’ll love the ones provided by SuperInvoice.

Once you have laid out the basic behavior, you specify how each of the editable columns will behave by adding to the list on the ‘Columns’ tab, and then setting its properties:

Settings)

Note how you can override the dynamically created control with one of your own (to, for instance, use a FileDrop template). You can perform file lookups on the column. You can conditionally disable each column. If you’ll note the ‘Date Entry’ tab, Super Invoice makes is easy to add ‘Quicken’ style date entry keys (pressing ‘T’ fills in today, + and – increment/decrement, etc.) as well as have a popup calendar. (The calendar procedure is provided as a TXA file, which must be imported into your app.)

Another nice touch is the ‘embeds’ tab. It offers six buttons to take you directly to the appropriate data and source embeds for the three primary methods where you would place your code for this field (TakeSelected, TakeAccepted and TakeEvent). Anything that helps to wade through the mass of ABC methods is highly appreciated in my book.

All in all, a strong set of template options that can be augmented via embeds as needed.

Performance

In a word, slick. It simply makes this type of parent/child single form update work the way that most people expect it to ("When I said Cancel, I meant Cancel!"). As a bonus, updating child items happens FAST since there is no file I/O (or network traffic) to slow the user down. As noted earlier, transactions are processed in minimal time as well, reducing the impact of Logouts on other users.

The only real downside to the SuperInvoice/queued child records system is if you have a really large amount of child records. In that case, it can take a while to load the form and/or save it. By definition, though, this type of process (Invoice, Purchase Order, Contact Manager, etc.) generally doesn’t have anywhere near enough child records to cause a problem.

Documentation

Documentation is provided in both printable Adobe Acrobat PDF format and as a standard Windows Help file. This gives you the best of both worlds, as you can have the paper docs on your desk for reference while still being able to pop up context sensitive help as you use the templates. The documentation also does a good job of describing the overall philosophy of SuperInvoice 4 and what changes have taken place in the move from the legacy template version to the ABC templates.

The demo app provides a decent introduction to SuperInvoice in action. It would be nice, though, if some sample data were provided. It was a minor inconvenience to have to type in products and customers before being able to actually work with the procedures that used SuperInvoice.

Technical Support

Technical support is provided both by Mitten Software (BoxSoft’s distributor) and directly by BoxSoft. Mitten provides phone and fax support as well as support via email. BoxSoft direct support is via e-mail, and the Clarion third party forums on CompuServe and the TopSpeed news groups.

Basically, in the course of both reviewing and working with BoxSoft products over the years, I have never found their support to be anything less than excellent.

Summary

BoxSoft’s stated goals for SuperInvoice (and indeed, all their products) are:

1. The feature must be easy to implement.
2. It must work with the regular Clarion templates.
3. All code must be visible in the template (i.e. no black-box DLLs).
4. The resulting programs should work intuitively and quickly.

After working with SuperInvoice for a period of time, I think I can safely say that they have succeeded on all accounts.

The Ratings

Category	Product Score
Ability to do the task	Excellent
Ease of use	Very Good
Ease of Installation	Good
Documentation	Excellent
Technical Support	Excellent
Modifies Shipping Templates	No
Black-Box DLLs/LIBs	No

BoxSoft’s SuperInvoice is available for US $119 from Mitten Software (1-800-825-5461). More information and ordering details are also available at the Mitten web site at: http://www.mittensoftware.com. SuperInvoice is also part of BoxSoft’s Super Demo, which can be downloaded from http://www.boxsoftdevelopment.com.

As noted at the beginning of the review, two versions are available, a 4.x version for ABC templates (C4 and C5) and a 2.5x version for the Clarion legacy templates (CW2.x, C4 and C5). BoxSoft has stated that future improvements will most likely only be made to the ABC version.

Printer-friendly version

Copyright © 1999-2008 by CoveComm Inc. All Rights Reserved. Reproduction in any form without the express written consent of CoveComm Inc., except as described in the subscription agreement, is prohibited.

Clarion Magazine ISSN 1718-9942