Super Tagging 2.20 - Boxsoft Development

Posted December 1 1997

Printer-friendly version

As developers, we all spend a lot of time implementing filters in our reports and processes which are based upon the premise that someone wants to see records selected by a logical set of rules. You know, stuff like 'Show me all customers from New York' or 'Just print invoices which are overdue'.

There are times, though, when that type of logic just won't work; when the user needs to be able select records randomly by, in essence, just pointing at them ('give me this one, that one, and, oh, yeah, that one, too').

However, while rule based filtering is easy to implement using CW's powerful View technology, it is an unfortunate fact of life that CW is sadly lacking when it comes to the random selection of records on a browse for use in a report or process.

Fortunately for us, Boxsoft Development's Super Tagging templates are designed to address this lack, and address it they do it in fine style.

Tag Tales

Tagging, or, as is it sometimes called, 'Marking', gives the user a way to select the records for a process or report at random, usually from a browse. Behind the scenes, your program needs to keep track of which records have been chosen (or 'tagged') so far, and to give the user some sort of visual feedback as to whether each record has been tagged yet or not. Typically, this means using icons (such as a check mark) or text (an 'X' or whatever) on the browse list to show the status of each record as tagged or untagged.

Once the user is through selecting records, the following report or process must be able to access the stored list of tagged records so that it can print or operate on only those items.

Let me count the ways...

As laid out in the documentation, Super Tagging supports five different ways of storing tags. Two of them store tags based on either a record pointer or primary numeric key value, the difference being that one stores the tags in memory while the other uses a disk file to store the tag values. These methods can be used if your data is either a) stored using a file driver that supports the Clarion Pointer() function, or b) has a unique numeric primary key, like a System or Customer ID.

A corresponding pair of methods allows tagging records by record position or primary alphanumeric key. Once again, one method uses memory while the other uses a disk file. These methods would be used in cases where either the file driver doesn't support Pointer() or the primary key is alpha-numeric. A good example of the latter might be a 'States' file where the primary key is the two-letter abbreviation.

The final method uses a single numeric field within the file being tagged which, for example, would be set to True if the record was tagged or False if not tagged. This method is usually used only in a single user environment, since there is only one possible set of tags. In a multi-user environment, you would have to ensure that only one user could tag at a time (an administrator, for example) or else it would be possible for everyone to be changing the tags at once.

In general, the memory methods are the fastest since they do not require file access for each tagging or untagging action. The primary drawback is that they only exist as long as your program is running. File-based storage methods have the opposite problem - they persist between sessions, but are slower. Fortunately, Super Tagging offers templates which nicely bridge the two methods and adds a host of powerful features as well, including the ability to save and restore sets of tags stored in memory to disk, under either user or programmatic control.

Using the Save Tags and Load Tags templates, your program can use memory tagging for speed while allowing the user to save sets of tags to a common disk file as often as they want. These tag sets can be named, combined, copied, saved, deleted and otherwise manipulated by the user (or you) in a number of useful ways.

My tags, your tags

Tags stored in memory are, by definition, unique to each particular machine.

Saving and Loading sets of tags in shared disk files, though, can present a problem in a multi-user environment if you need to ensure that user A's tags aren't being mixed up with user B's. Super Tagging provides automatic support for saving Tag sets under UserIDs if you are using Boxsoft's Super Security templates. If you are using some other means of identifying users (DAS_Security, SecWin or security of your own, for example), you can easily pass your own UserIDs to Super Tagging with a single function call at the beginning of your program.

If you don't use any UserIDs, you can either store the tag files on the individuals' machines, or simply use the saved sets as a sort of 'global' resource for all users.

Installation

I downloaded the most current version of Super Tagging direct from the Boxsoft web site (www.boxsoftdevelopment.com). It was provided as a zip file, with the zip containing a 'read.me' text file and a standard Windows all-in-one installation program. The install program itself is password protected, with the password being provided when the product is purchased.

After unzipping the package to a temporary directory and running setup, the program proceeded with a typical install - asking where CW was located, verifying the password and then installing itself into a set of directories under a directory called \CW20\SUPER.

Because the files are not installed in the default CW locations (templates in \CW20\TEMPLATE, for example), you must edit your CW20.RED (path redirection) file to enable CW to find the files required by the Super Tagging templates. This brings us to the most awkward part of the install process...

Seeing RED

The easy part of having to change the RED file is that Boxsoft provides clear step-by-step instructions in the online documentation, and even gives you a sample RED file to go by. The problem? Well, I had glanced at the small READ.ME file which accompanied the setup program, finding it rather hard to read because Notepad was displaying what were obviously supposed to be line characters as all sorts of accented letters. Whatever the reason, I missed the one line in it that stated where the documentation was going to go, and consequently, reached the end of the installation without a clue as to what to do next.

I was left to poke around in the SUPER directory, find the DOC sub-directory under that and then locate the PDF file which contained the manual. Once I had found it, though, performing the required edits was simple enough. I do think, though, that the Super Tagging installation process could be enhanced by adding a final 'What to do next' screen near the end of the installation. This screen would be the logical place to point out where and how to get to the documentation, mention the RED file, and just generally keep the installation process flowing a bit more smoothly. I guess my theory is that information this important should be placed where you can't miss it.

Displaying the Super Tagging Help file at the end of the installation would also be a nice touch as this allows new users to begin familiarizing themselves with their new tool right away.

Note: If you have installed other Boxsoft products previously, your RED file will in most likelihood already have the required modifications since all Boxsoft products share the SUPER directory. You should still check, though, to make sure that new categories have not been added since your last Boxsoft installation.

Putting it all together

Ok, we've installed the package, edited our RED file, and registered the templates - time to jump right in, right? Well...

Featured prominently in both the printable documentation and the help file is an 'RTFM Warning' - an admonition to Read The ...er, Fabulous Manual. As it states, Super Tagging is easy to implement if you follow the steps that the manual lays out. This is not a template that you can just jump into blindly, as it requires that you understand the various tagging methods described earlier, and just how they relate to your files and keys.

The basics

After reading though the manual to acquaint myself with how Super Tagging works, I followed the step by step instructions to add tagging support to the CW Maillist example application. During the first pass, I simply wanted to be able to tag people and then run a report that printed labels for only those people. In a nutshell, here is what it took:

1. Add the Super Tagging Global Extension to the app and make a few basic choices such as which types of tagging I wanted to use and which file driver should be used to hold tag and tag set information.
2. Open the People browse procedure and add the 'BrowseTaggingButtons' control template to the browse Window. This populated a total of eight buttons on the window for all of the basic tagging options (tag, untag, flip, tag all, untag all, etc.). A quick trip through the tagging template options let me specify that I wanted to: a) store the tags in memory, b) have icons on the tagging buttons, c) have icons appear next to checked items on the browse, and d) have the pointer automatically move to the next record whenever a person was tagged.
3. Added a column to the browse for the tagged item icon (a check mark, in this case) and saved the browse procedure.
4. Opened up a report and added an extension template to limit the report to tagged people. This was accomplished by filling in a prompt that told it to use the same tag set as the people browse was using.
5. Saved the report, compiled the application and ran it.

Everything worked exactly as expected. Tagging a People record resulted in a green check mark, untagging removed the check, etc. While I was running the report, it asked me if I wanted to limit the report to tagged records. Answering yes, I saw the report with only those people that I had just tagged while on the browse.

Pretty slick. Total implementation time so far - approximately 15 minutes or so.

Getting Fancy

Next, I wanted to give the user the opportunity to save and restore sets of tags, as well as the ability to switch between viewing tagged records, untagged records and all records on the browse. So, it was back to the browse procedure, and to make a short story even shorter, after adding a few more control templates and compiling, there was everything I wanted, as shown in the following screen shot.

Example Application with tagging options

Total implementation time: About 35 minutes including time spent tweaking button sizes, etc. - and not a bit of handcode in sight. The templates even automatically provided the procedures needed to browse, select and update tag sets (used by the Load Tags/Save Tags buttons).

The need for speed

Performance is always an issue in applications, and Super Tagging supports multiple ways to optimize the process of using tags. Fastest, of course, is using memory tags, since disk- based tagging is subject to all of the usual slowdown culprits; slow drives, clogged networks and overloaded servers.

For processes and reports, the simplest method of filtering for tagged records can also be the slowest - it simply reads all of the records and rejects them if they are not in the tag queue or file. Obviously, this can be a problem when you have a large data set and few tagged records. Super Tagging does, however, provide is a nice compromise that gives the best of both worlds but requires a bit more setup on your part. It involves importing the TagFile definitions into your dictionary from a supplied TXA file, and then relating your data files to the tag files. Once this is done, though, you can specify the TagFile as the primary file in reports and processes and use a special extension template to handle reading the tag file and retrieving the data records. Using this method, you can use tags against huge data files with no loss in performance since only tagged records are processed or printed.

All together now

One very important thing to keep in mind when implementing tagging is that you must keep the tag storage methods consistent for a given tag set when you are filling in template prompts. Specifying that the tags are stored by pointer/primary key on the browse and by pointer/position on a report will compile just fine, but it will yield very strange results when run (as I found out).

Note that you can mix and match tagging methods as much as you want between tag sets; you just need to be consistent within each set. For example, you could have tags from a 'States' file stored in memory by Position/Primary key, since it is unlikely that your States file would have unique numeric ID's assigned for the States. For your People file, on the other hand, you could specify that tags are stored in a disk file using a primary numeric ID as the key.

Bonus time

There are a lot of nice touches included in the Super Tagging package. Icons are provided for all of the various buttons if you want to use them and, in some cases, you can choose from more than one style. Don't like check marks? No problem - you can choose from a list of check marks, boxed check marks or X's , circles with dots, and more.

Virtually all tagging options, behavior and messages are easily set through template prompts. For example, providing right-click popup menu support for the basic tagging options was added simply by turning on an option on the tagging template.

If you just can't live with what Boxsoft provides, however, the templates give you the option of using your own icons and messages, etc. Additionally, a TRN file is provided for translation of Super Tagging prompts, etc., into other languages. You can also import the tag set browse and update forms into your app from a provided TXA file. This gives you complete control over the look and feel of those procedures as well.

If you need to move beyond the top level control and extension templates, Boxsoft also provides a set of mid-level code templates which can be used in embeds to perform most common tagging functions without having to learn the syntax of the those functions. These include opening and closing tag files, tagging/untagging/flipping records, copying tag sets and loading, saving and wiping (deleting) a tag set.

Finally, for those special situations where you require total control of all tagging functions, you can also use the tagging library directly from hand code. The functions themselves are fully documented in the Super Tagging manual.

Doing it the 'Windows' way

In addition to the 'standard' methods of tagging described above, Super Tagging also supports 'Windows-style Marking'. This is the kind of behavior you see when selecting files in the Windows 3.x File Manager or Win95 Explorer, where holding down the shift key and clicking selects a range of items, and pressing control and clicking selects one item at a time. Instead of using icons or text to indicate the tagging status, each selected item is highlighted in the browse.

There are a couple of caveats associated with this method, though. The first, noted by Boxsoft in the manual, is that this method should not be used with data sets containing more than a few hundred records since the templates use a 'brute-force' method to select ranges. For small sets of data (selecting states, for example) or for browses that are using a small subset of a larger file, it should work fine.

Second, in my experimentation with the various combinations of templates, I found that the control template, which alternates a browse between showing all records, just tagged records or just untagged records does not seem to work with Window-style Marking. Although the internal queue of marked items was correct, switching on the browse wasn't showing the right combinations of items. Of course, this is a rather non-standard combination in itself, so I don't really fault the templates for it. It should, however, be noted in the manual that you either shouldn't use that combination, or that they should be made to work together.

Documentation

Printable documentation is provided in Adobe Acrobat PDF format. This format allows you to either view the manual online or print it out via the Adobe Acrobat Reader. Chances are VERY good that you already have the free Reader program, since it has been included on all recent CW CD-ROM disks (look in the 'Acroread' directory). It can also be downloaded from www.adobe.com or CompuServe.

The Super Tagging manual is oriented in a basic 'how to' direction, and answers to most questions can be easily found within it. There were a few omissions, though. For example, the definitions of the Tagfiles and the memory queue used to hold the tags are not shown in the Function Reference section, even though other global variables are.

The only way I could see to find out what those definitions were was to either import the files into my dictionary and/or to view the source code for the main program module. It would be nice to have a few more details like these accessible in the manual since they are so core to the templates.

Besides the manual, two example apps are provided which demonstrate the proper usage of most of the tagging templates. They are pretty much identical except for the way they access the Super Tagging functions - one places the functions inside your program while the second demonstrates how to put the tagging functions into a DLL.

The package also includes a template Help file that basically mirrors the contents of the PDF file.

Technical Support

Technical support is available from both Mitten Software (Boxsoft's distributor) and from Boxsoft itself. Mike Hanson, the author of the Super line of templates, provides direct support on the CompuServe TopSpeed forum, and consistently gives his products good support there. My own questions were answered promptly with either code examples or, in one case, an example of how to modify the templates if I wanted to change their behavior.

Suggestions for Improvement

Being one of those users who, when faced with a pretty comprehensive product, can always think of at least a few more features which would be nice to have, here is my wish list for Super Tagging:

• Allow the use of radio buttons to select between viewing tagged, untagged and all records on browses. The current implementation uses a single button and works fine, but it can be confusing to have one button that toggles through three states, and is always showing you the next viewing option instead of the current one.
• The tagging library provides for an alternate sort field within the tag files and queues; however, I could find no way to use it from the templates.
• The 'Get Tagged Records in a Process' template for reports and processes (the one that does direct access on the TagFile) doesn't currently support using either of the 'memory' tag storage options. It would be nice if it did, as this would give you the absolute fastest processing of tagged records. The closest you can get at the moment is to use a provided 'mini-process' code template, but this still leaves out reports.

Summary

Super Tagging appears to be another solid product from Boxsoft Development and, aside from the hiccups with installation, it provides a very flexible and easy to use front end for what can be a fairly complex process. I also like the fact that the templates give you so many options for storing and retrieving tags, allowing you to optimize for both small and large sets of records based on almost any kind of file structure. Finally, I was impressed with the nice touches like the inclusion of so many icons and the ease with which you could choose from different icon schemes.

As stated earlier, for those who prefer to roll their own, the tagging functions are all documented and, like all Boxsoft products, everything is simple generated Clarion code (no lib's or black box DLL's).

Super Tagging retails for $69 US, and can be ordered through Mitten Software at www.mittensoftware.com or via the phone at 1-800-825-5461.

Article comments