Volume Number: 15 (1999)
Issue Number: 3
Column Tag: Pluggin-In

Writing a Module for Document Express

by Evan Trent

Harnessing the power of Document Express' email and database engines

Bulking Up

In the modern world of the information age even the smallest corporation cannot afford to manage its various forms of communication ineffectively. Electronic mail, in particular, has quickly become the most unruly form of communication from a managerial and administrative perspective. The shear volume of email which even a mere individual must process during any given work day can often seem daunting. However, email is also a precious commodity for any corporation or individual. The names of customers, their associated order information, problem, suggestion, and even lunch date confirmation, is locked safely away on countless hard drives on countless corporations' computers throughout the world.

Much thanks to a new software application, Document Express (or DE), the task of providing the fancy features of an automated and well managed email system has been reduced to a simple sequence of keystrokes and mouse clicks. Document Express is advertised as an "interactive relationship management system" and that description is certainly quite appropriate. DE's most obvious selling point is in its broadcast email capabilities, but that is hardly the limit of DE's communications arsenal. DE can send out personalized responses to emails received from any POP3 mailbox. This can prove particularly useful when managing data-gathering HTML-based forms and providing the user with automatic confirmation of their submission. So while DE is, at its simplest level, a broadcast messaging system, it is really much more: it's a contact management system, POP3/SMTP email engine, interactive email system, and extensible application with a powerful and well implemented plug in architecture.

I was first introduced to Document Express when I reviewed version 1.0 for About This Particular Macintosh (http://www.atpm.com) in August of 1998. Mark Teixeira, developer of Document Express, contacted me immediately following the publication of the review and conveyed a genuine desire to improve DE as per my criticisms. Recently I received another email from Mark announcing that version 2.0 had been released and that he would like me to re-evaluate Document Express in another review for ATPM. Aware of the fact that I am, aside from an overly harsh reviewer of Macintosh software, a C/C++ programmer, Mark asked me if I would consider writing an article discussing the development of a DE plug-in using the Document Express SDK. After reading through the SDK documentation I was convinced that this task would be fun and only moderately challenging much thanks to the strong documentation Mark has provided with the SDK.

Modulating a Module: Bozo's Birthday

The Dilbert era has brought forth a trend of intra-corporate email discussing everything from blonde jokes to board meetings. Some examples of the subjects of these emails might be: Reset Your Clock, Vacation Schedule, Weekly Meeting, Daily Units Sold, New Beta Release, Training Seminar, Bozo Submit Your Timesheet, and most importantly Happy Birthday! Corporate related emails are often chunks of text with very slight variations from recipient to recipient. Wouldn't it be nice if a Mac could automatically generate email messages based on submissions received from an HTML form, for example? Imagine how this could simplify and expedite operations. This will be our task: to develop and implement a DE module which, based on a submission from an HTML form, generates and delivers a personalized email announcement. We will call this project Bozo's Birthday.

This module will function much as expected. As dictated by a user defined time interval the module will check a user defined POP mailbox for new Bozo Birthday messages. The resulting email(s) will then be parsed and processed for pertinent data. The data from the email(s) will then be used to generate an outgoing message based on a pre-defined template, or in DE terminology: mailform. The module will then send the outgoing message to all the marked entries in the currently open DE database file. The process is entirely automated and nearly every variable may be assigned a value remotely via the HTML form.

Getting Started

Document Express modules are Code Resources, just like HyperCard XCMD's or 4D externals. They may contain additional resources as needed: Dialogs, Menus, strings, icons, etc. Each code resource has a main entry point, with a clearly defined parameter list, or prototype. The main function must be defined properly, or the module will not link. The prototype definition for the main function can be found in the file ModuleCallback.h, which is included with the DE SDK.

CallBacks

Document Express has implemented a number of callback routines that module developers will find essential in creating DE modules. These callback routines are accessed by a global pointer which is passed into the module at initialization time. "ModuleCallback.h" defines all of these callbacks and provides handy macros to call these functions from a module.

DE callbacks are grouped together loosely based on the general class of functionality. DE supports callbacks for window management, database access, menu and palette interaction, contact and document manipulation, plus many utility callbacks to assist in drawing, spell checking and working with dialogs. Document Express also supports POP3/SMTP through TCPCallbacks, a fully implemented email engine which can be used from the SDK to send and receive email messages. The POP3/SMTP callbacks are highlighted in greater detail later in this article.

High Level Event Basics

Document Express maintains an internal array of open modules, and passes these modules high-level events when appropriate. When a module receives an event from Document Express, it must first determine the event's high-level message grouping. There are seven different messages groups:

      H_SYSTEM_MESSAGE      
      H_TOOL_MESSAGE
      H_WINDOW_MESSAGE
      H_DATABASE_MESSAGE
      H_BUTTON_MESSAGE
      H_MENU_MESSAGE
      H_MERGE_MESSAGE.

An H_SYSTEM_MESSAGE gets passed to a module at important startup and shutdown (HS_INITIALIZE and HS_CLOSE) times. Additionally, HS_IDLE is sent to a module periodically (note that "windows" get their own idle messages). HS_IDLE proves useful in keeping track of timer value for a trigger. HS_HIDE_ALL_WINDOWS and HS_SHOW_ALL_WINDOWS are system messages that are used to manage a module's window(s).

Document Express will handle drawing a module's icon suite in the tool palette as well. All the programmer need do is provide DE with a 'hMis' resource which points DE to an array of 'cicn' resources. Three consecutively numbered 'cicn' resources must exist for a module: an icon for "normal" state, "pressed" state and "active" state. DE tracks mouse clicks on the palette automatically, and is responsible for maintaining the various icon states.

Occasionally, it may be desirable to draw a figure or shape in the palette dynamically. In this event, a module must not supply a default icon suite, and must listen for specific H_TOOL_MESSAGE messages. The selectors which further define H_TOOL_MESSAGE are numerous. Generally speaking, a module will be notified when it must draw each part of its owned rectangle: the background, contents, name, and the three icon states. When a module must perform its drawing, DE takes care to set the window port, clipped to the icon's rectangle. DE will restore the port when drawing has completed.

The majority of the source code for a module will appear in the window class. The DE message H_WINDOW_MESSAGE, and its accompanying 25 selector messages, provide a developer with ample power to manage even the most complex window scenarios. Familiar high-level Macintosh events are translated into HW_KEY, HW_UPDATE, HW_CLICK, HW_CLOSE, HW_ACTIVATE, HW_IDLE, HW_CURSOR_CHANGE, and HW_DEACTIVATE messages.

The Document Express database message H_DATABASE_MESSAGE is sent to each module when a change occurs to a DE database or a database record. For example, a module will be notified when a new database has been opened, created or closed (HD_OPEN_DATA_FILE, HD_NEW_DATA_FILE, HD_CLOSE_DATA_FILE). In addition, changes in a contact entry record generate messages as well (HD_ENTRY_ADDED, HD_ENTRY_DELETED, HD_ENTRY_SET, HD_CURRENT_ENTRY_CHANGED).

Creating and handling buttons in a module is relatively easy. The SDK defines a button bar array, which Document Express manages internally. This array was designed to provide developers with a means to conform easily to DE's interface. DE's UI was engineered around the concept of limiting multiple open windows by providing separate "views" within a single window. Changing views usually means maintaining separate button groupings. The module SDK allows a module to easily manage several different button arrays, and handles tracking and displaying these arrays automatically.

Figure 1. A module's window and button bar.

Document Express offers the developer opportunities to respond to the DE menu system by passing a module various menu messages at appropriate times. If a module's window is the front most window, DE will send messages asking if a particular menu item should be enabled or disabled. The module will be sent a HM_COMMON_CANCHOOSE messages when one of the "common" menus (Apple, File and Edit) is clicked. Likewise, a module will be notified when a choice has been made via HM_COMMON_CHOICEMADE. The definitions for each "common" item can be found in the ModuleCallback.h file. Additionally, modules may place their own menu(s) in the menu bar, and they may also append the Apple, File and Edit menus at pre-defined places.

Rounding out the message suite are H_MERGE_MESSAGE and H_COMMAND_MESSAGE. The former will be sent to a module when a "merge" condition arises within a Document Express document, usually at times before Print or Broadcast. This flexibility allows modules to maintain their own merge data, thus expanding the merge capabilities to include not only the 32 built-in contact fields, but additional fields with their own sources of input. We will discuss the H_MERGE_MESSAGE in greater detail later in this article.

An H_COMMAND_MESSAGE will be sent to a module if it is specified as type "Broadcast Capable." Modules of this nature are assumed to be able to handle some sort of communication with an outside port or service and are responsible for broadcasting the contents of a document to a select group of recipients. The H_COMMAND_MESSAGE selectors are H_COMMAND_INIT_SERVICE, H_COMMAND_SEND_SERVICE and H_COMMAND_QUIT_SERVICE. Document Express supports broadcast email internally, and broadcast fax via dedicated ISP's, or through FAXstf's fax software (see the module Fax Browser).

Each message group has an accompanying selector set, which further defines the higher-level message. For example, when a module window receives a mouse click, Document Express will pass the module a H_WINDOW_MESSAGE, with the accompanying selector HW_CLICK.

Fortunately, the module class library organizes the message groups and their accompanying selectors into a well-defined object oriented dispatch mechanism. This construction alleviates the need to write any high level dispatching code, and allows you to work with DE messages within a familiar object format.

The scope of Bozo's Birthday will require us to override just one class: the HWindow class. This class handles the dispatch of window related events such as mouse clicks, update and activate messages, idle messages and so forth. We will override this class with a new class called BBWindow. BBWindow provide us the framework for adding our own code. By overriding the HWindow class with our own BBWindow class, we can receive the more appropriate DoClick message, with the more useful Point and Modifier parameters.

Creating the Project

The Starter Project that accompanies the DE SDK will serve as our basic framework as it supports the basic implementation of a DE module. Additionally, Starter does a nice job of incorporating the DE module class library, which in turn organizes DE's system of sending high level events into familiar and predictable classes and class methods.

In the main() function, found in the file main.c, we will be listening for the H_SYSTEM_MESSAGE message, with the selector HS_INITIALIZE. This message tandem gets passed to each module at startup. When our module receives this message, it must first create the HModule object. This object manages the class library, creating internal objects for contact management interaction (HContact), internal message dispatching (HDispatch), tool palette interaction (HToolPalette) and a preferences object (HPreferences). One may ignore these classes entirely, but they must be set up at HS_INITIALIZE time. Now we can create the BBWindow object. Once created, we will initialize the class, and allocate a window with the appropriate dimensions. Document Express automatically handles opening, zooming and closing module windows.

Listing 1: Main Entry Point Into the Code Resource

main

pascal long main(short messageType, short message,
long param1, long param2, DEParamsPtr hPtr)
{
   long result = 0;

   EnterCodeResource();
   switch( messageType )
   {
      case   H_SYSTEM_MESSAGE:
         if( message == HS_INITIALIZE )
         {
            //   Always setup/remember our global pointer and module ID.
               deParamsPtr = hPtr;
               gModuleID = param1;
               
            //   Setup the email interface
               setUpTCPCallbacks();
            
            //   allocate our objects.
               gModule = new HModule;
               gModule->IModule();
               
               gWindow = new BBWindow;
               ((BBWindow*)gWindow)->IBBWindow(gModuleID);
            
            //   register our merge fields
               WRRegisterMergeField(param1, 'BOZ1');
               WRRegisterMergeField(param1, 'BOZ2');
               WRRegisterMergeField(param1, 'BOZ3');
               WRRegisterMergeField(param1, 'BOZ4');
         }
         else result = gDispatch->HandleSystemMessage(message, param1, param2);
   ExitCodeResource();
   return result;
}

In the file BBWindow.cp, we will define one method, IBBWindow. In this method we will allocate our window. The superclass method HWindow:IWindow() is the easiest way to create a Document Express "style" window. IWindow is responsible for managing the Macintosh WindowPtr and registering the window with Document Express.

Listing 2: Allocation of a Module's Window

BBWindow::IBBWindow
void BBWindow::IBBWindow(long aModuleID)
   {
   HWindow::IWindow(aModuleID, zoomDocProc,
            MIN_WINDOW_WIDTH, MIN_WINDOW_DEPTH, MAX_WINDOW_DEPTH,
MAX_WINDOW_DEPTH, FALSE, FALSE, "\pBozo Birthday");
   }

Next it is necessary to create a button and place it in the BBWindow window. Luckily DE offers programmers the high-level tools needed to make a module's appearance conform to the DE interface. For example, DE has a well-defined button scheme which enables programmers to establish a standard interface across all of their modules.

When pressed, our button will log on to a POP3 server, and check for new messages. In the BBWindow.cp class, we must override the method InitButtonBars. This method is called during HWindow::IWindow. Overriding this method offers us the opportunity to set up the window's button bar array with controls, and allows us the opportunity to provide specifications regarding the control's characteristics, for example: behavior, appearance, function.

Listing 3: Initialization of a Button Bar

BBWindow::InitButtonBars
void BBWindow::InitButtonBars()
{
   #define   kNumberButtonBars   1
   #define   kNumberOfButtons      1

   buttons->numberOfButtonBars = kNumberButtonBars;
   buttons->buttonBars[0].numberOfButtons = kNumberOfButtons;
   
   //   initialize the button with a callback routine, name,
   //   type and icon artwork.

   buttons->buttonBars[0].buttons[0].clickProc = CheckForBozo;
   buttons->buttonBars[0].buttons[0].name = MakeButtonNamePtr(kButtonNames, kCheckNowName);
   buttons->buttonBars[0].buttons[0].type   = H_BUTTON_TRIPLE_CICN_CNTL;
   buttons->buttonBars[0].buttons[0].iconID   = kMDoSomethingNowIconGroup;
}

When the button is pressed DE will jump to the address specified in the clickProc variable. From this clickProc method, we will directly call the BBWindow class via the gWindow global. We do this because it is a good organizational strategy given the register setup and restoration we must perform within the button press callback.

pascal void CheckForBozo(ClickEventPtr /*e*/,
                         ButtonDefPtr /*b*/,
                         short          /*choice*/)
{
   //   setup and restore A4, as we are being called directly from DE.
   EnterCodeResource();
   ((BBWindow*) gWindow)->CheckForBozo();
   ExitCodeResource();
}

Once within the code attached to the clickProc variable, we can now perform the task of logging into the POP3 mailbox and looking for messages. The DE SDK comes with a header file which we need to include with the project headers if we wish to utilize DE's email engine. The file TCPCallbacks.h defines a complete implementation of POP3/SMTP. Using these functions gives us complete control over a POP3 e-mail box and a messaging transport server (SMTP). To access these methods, we must first declare the TCP global variable 'TCPFunctionsPtr TCPPtr' in our code. We must then call the function setUpTCPCallbacks, preferably at module init time. After calling setUpTCPCallbacks, we can then use the e-mail callbacks (refer back to the function main).

Email Euphoria

Document Express's SDK makes it very simple to establish a connection with a POP3 mailbox. First, we must establish a link to the email engine by calling the function ENewConnection. ENewConnection returns a long which is used as a parameter for every subsequent email function call. ENewConnection takes two parameters, the global module ID and a boolean which indicates to the engine whether or not it should display a status window.

   long connect = ENewConnection(gModuleID, TRUE);

Once the connection has been initialized, we must register our logon parameters with the email engine.

ESetLogonPParams(gModuleID, connect, 
        "popusername", // POP3 user name
"mail.yourserver.com", //   POP3 mail server
               "\p",   //   empty. used for SMTP
"yourpassword");       //   POP3 password

Finally, we perform the logon. Document Express will handle errors internally and display the appropriate error message with an error code.

   OSErr err = EPOPLogon(gModuleID, connect);

Now that we have established a connection with the remote mail server, our next task is to check for new messages. The easiest way to do this is to query the server for the current message count.

   long totalCount;
   OSErr err = EPopMsgCount(gModuleID, connect, &totalCount);

For the sake of Bozo's Birthday, we will employ a simple strategy of iterating through each message on the mail server, and looking at the message header only. Specifically, we are going to look at each message's subject header, looking for email messages titled _bozo_birthday_. Once we have encountered a message with this subject, we will download the body of the message and parse it for the pertinent data.

To accomplish this, we use the EPopMsgTop function, which allows us to only download the message's header information. Once the message header has been downloaded locally, we can use the query callback ERead1Field to access the data found in the message header.

   long foundBozo = 0;

   for( long i = 1, i <= totalCount; i++ )
   {
      Handle h;
      Str255 subject;

      err = EPopMsgTop(gModuleID, connect, i, 0, NULL);
      h = ERead1Field(gModuleID, connect, em_Subject)
      if( h != NULL )
      {
         HLock(h);
   C2PStrCopy(*h, subject);
   DisposeHandle(h);
         
         if( EqualString("\p_bozos_birthday_", subject, 0, 0) )
         {
            foundBozo = i;
            break;
    }
    }
}

Once we have identified a _bozo_birthday_ message on our mail server, we can then download the message from the server using the EPopMsgRead function, which retrieves the entire message. The last parameter which EPopMsgRead takes is a Boolean which determines whether or not the mail server should delete the message after it has been downloaded it. A value of TRUE signals to the mail engine to delete the message.

   if( foundBozo > 0 )
   err = EPopMsgRead(gModuleID, connect, foundBozo, true);

We have now successfully created a connection to a POP3 mailbox, determined the message count, iterated the mail box and downloaded a message. At this point, there may be some confusion as to how the _bozo_birthday_ message ever got sent to that POP3 mailbox in the first place. Another source of confusion may be the format of the message. Before we go any further, we will digress a little into the magic of mailforms, and the beauty of paramaterized, smart email messaging.

Smart Email

Document Express takes a unique approach to Email messaging. DE views Email as data which can be regarded in the same context as database records. This is a perfectly reasonable approach: each Email record resides in its own flat file database on a remote server, and can be accessed via a simple query language. The schema of an Email record is trivial; a header, which gives addressing and format information, and a container for the message body, usually text, but sometimes pictures, sounds, file enclosures or other arbitrary data.

Document Express' Webform is a perfect vehicle to better illustrate the workings of parameterized Email. Webforms employ FormMail, a modification of Matt Wright's PERL script, which can organize data from an HTML form into a parameterized Email message. Typically, a visitor to a website will encounter a form, type values into fields and/or select items from popup menus, lists, check boxes and radio buttons. When the user presses the Submit button the HTML code points to a CGI, in this case the FormMail PERL script, and the HTTP server sends the data from the form on to the CGI. At this point FormMail takes over and neatly packages this data into a well-defined email message and delivers it to a pre-defined email account.

Setting up a Document Express' Webform to capture data is easy. It is the perfect way to administer an interactive website. For Bozo's Birthday, we need to capture only four pieces of information to successfully implement our task; Bozo's name, birthdate, party time and location.

Before we can use our HTML form to capture the Bozo vitals, we must configure it for use with FormMail. First, assign a subject to the form. This subject will be used later to determine if the email is a Bozo Birthday message. Secondly, we need to assign an address to which FormMail should deliver the form once it has been processed and turned into an email record. We can do this with the following two lines of HTML code.

<input type="hidden" name ="subject" value="_bozos_birthday_">
<input type="hidden" name ="recipient" value="some@address.com">

Now that we have added the constants, so to speak, we can setup the three data fields to capture the Bozo variables:

Bozo's Name:   <input type="text" name ="Name" SIZE=30 MAXLENGTH=30><br>
Birthdate:      <input type="text" name ="Bday" SIZE=30 MAXLENGTH=30><br>
Location:      <input type="text" name ="Loc" SIZE=30 MAXLENGTH=30><br>
Time:         <input type="text" name ="Time" SIZE=30 MAXLENGTH=30><br>

The resulting Email record, processed by FormMail and delivered to the destination Email address, will have roughly the following format:

Name: Johnny Rocket+_+
Bday: February 20+_+
Loc: the patio terrace+_+
Time: 1:00 P.M.+_+

The data values from this form will be packaged and sent to the email box some@address.com. The next time our module checks the email account, it will encounter the _bozos_birthday_ message, download it, parse the fields Name, Bday, Loc, and Time, load the values into our own special merge fields which we have previously registered with Document Express, and send the message to all the marked contacts in the currently open DE database.

Magnificent Merge Fields

One of DE's many neat tricks is its ability to merge data from any of its 32 contact database fields and deliver a personalized message to members of a database file. Additionally, modules can create and maintain their own merge fields, so adding data, which is beyond the scope of the internal contact system, to a message is possible. In our mailform we will want to use the Bozo's name, birth date, party time and location information in addition to the recipients' first name. When the message finally ends up in the recipient's in box, it will read like the following (the data in BOLD indicates data which has been merged into the message before it was delivered).

Dear Fred,

We would like you to join us in celebrating the birthday of Johnny
Rocket on February 20 at the patio terrace at 1:00 P.M. We will be
serving coffee, soda, cake and ice cream.

Looking forward to your presence,

Linda Sunshine
Personnel Manager

Document Express has implemented a clearly defined mechanism for allowing developers the means by which they can add their own merge data to any DE document. To register our own merge fields, we the DE callback WRRegisterMergeField. In addition we will be listening for two messages that will be passed to us at the crucial times of substitution, HMM_GET_TITLE and HMM_GET_TEXT.

We will go back to the module initialization routine, described at the beginning of our discussion of modules. We must register our merge fields with Document Express at initialization time. Once our merge fields are registered, the end-user, who is creating the mailform document can select our merge fields from the list of fields. Our fields will appear at the bottom of the field popup menu, can be placed in any document, and will appear seamless to the user who is creating the mailform.

To register our Bozo merge fields with DE, we use the callback WRRegisterMergeField. The first parameter to WRRegisterMergeField is our global module ID, and the second is a 4-char OSType, which identifies the merge field. Note that these 4-char OSType values must be unique, and must not clash with the internal DE fields types (refer to the file ModuleCallback.h for a listing of DE's 4-char OSType definitions for its internal fields).

WRRegisterMergeField(gModuleID, 'BOZ1');
WRRegisterMergeField(gModuleID, 'BOZ2');
WRRegisterMergeField(gModuleID, 'BOZ3');
WRRegisterMergeField(gModuleID, 'BOZ4');

When the user is editing a mailform, it can be in one of two different states: merged or unmerged. Ordinarily the user edits a document in the unmerged state. However when the user presses the 'Preview' button, or before the mailform is about to be printed or delivered by email, the document is presented in merged state. When a document's state changes to the merged state, our module will be notified that it must supply the data for substitution. Document Express will pass our module the message HMM_GET_TEXT, and the address of a buffer which we will use to copy our data.

Figure 2. A mailform in unmerged state.

Conversely, when the document is in unmerged state, Document Express will send our module the HMM_GET_TITLE message, and again, we must copy data into a buffer. However, in the unmerged state, we will copy the field's label, as we would like it to appear in the document and the popup list of merge fields. We title our fields <Bozo Name>, <Bozo Birthday>, <Bozo Place>, and <Bozo Time>. (Note: it is not necessary to add the angle brackets, as DE will do this).

Delightful Databases

As a change of pace, we will now discuss the Document Express database engine, and what we can do with it in terms of the SDK. Document Express has a well implemented API for extracting contact information. For example, a module can obtain any field's value from any contact record. By extracting field data, a module can iterate the entire database, looking for records which match a certain criteria, such as Category = Sales, or State = CA.

For Bozo's birthday, we will be iterating the currently open database, searching for Marked records. Marked records are those entries which appear in list view with a small check mark next to them. One may mark records for various reasons; marking records provides a quick way to make a record part of a group.

To count the number of marked records in the currently open database file, we use the DE callback DBNumberOfMarkedEntries.

long n = DBNumberOfMarkedEntries(gModuleID);

//   use n to iterate an entire DE database, looking for marked contact
//   records
//   id is the marked record's sequence number, a unique 32-bit value
//   which identifies the record.

for( long i = 0; i < n; i++ )
   id = DBEntryIndexToEntryID(gModuleID, DBMarkedToEntryIndex(gModuleID, i));

Now that we have a means of iterating through the database and identifying marked records, we must extract the email address for each one we encounter. Once we are in the possession of the marked contact's email address, we can use the DE callback WRSendADocument. WRSendADocument is responsible for sending a document via email. WRSendADocument automatically detects the presence of merge fields in a document, and will take the appropriate steps to call back into our module, allowing us to perform our data substitution.

Here is a source list for the base processing of Bozo's Birthday.

   short    len;
   long       rsn, n    = DBNumberOfMarkedEntries(gModuleID);
   Str255   mailTo;
   Str255   mailFrom = "\pLinda Sunshine <linda@feelgood.com>";
   Str255   subject   =   "\pLet's Celebrate!";
   Str255   document = "\pBirthday Celebration";

   for( long i = 0; i < n; i++ )
   {
         //   obtain the marked record's sequence number

         rsn = DBEntryIndexToEntryID(gModuleID, DBMarkedToEntryIndex(gModuleID, i));
      
         // obtain the contact's email address.

         len = sizeof(Str255) - 1;
         DGetFieldData(gModuleID, rsn, H_D_EMAIL1,(char*) &mailTo[1], &len);
        mailTo[0] = len;

         //   send the document using the DE callback.

     err = WRSendADocument(gModuleID, connect,
               
               //   DE document to send
               document,
               
               //   mail-to address
               mailTo,
               
               //   mail-from and reply-to address headers
       mailFrom,
               mailFrom,
               
               //   the message subject
               subject,
               
               //   carbon-to (BCC) address (if necessary)
               "\p",
               
               // word-wrap text before delivery
               TRUE,
               //   the record sequence (used internally by DE)
               rsn);
}

Parsing

Back when we logged onto the POP3 mailbox, and correctly identified and downloaded a Bozo email record, we should have parsed that message. Having extracted our Bozo data we would then place that data into globals which we could use when our module gets sent the HMM_GET_TEXT merge message.

Knowing how FormMail formats our data, we can easily build a parser to extract the field data from the rest of the message. The FormMail PERL script file which accompanies DE places discreet delimiters at the end of every field's value, which explains the funny +_+ sequence found at the end of each line of data. Building a parser to extract the data values from the accompanying field tag is trivial.

Branching Out

Finally! With all our ideas and technology in place, we can now build a fully-featured module which supports the notion of Bozo's Birthday. We can also get more sophisticated: we can support other, more complex broadcast scenarios. For example, why couldn't our Webform webpage support other parameterized office situations, like the ones discussed earlier in this article. Surely, we are just a few more parameters away from Bozo Submit Your Timesheet, Bozo Set Your Clock, and Bozo Be At This Meeting.

Not Just an SDK

The Document Express Module Developer's Kit is robust in its implementation. Tools such as the Software Developers Kit and the Module Class Library (MCL) offer developers a familiar architecture for creating their modules. Document Express encourages developers to use the SDK by providing a fully licensable and reusable application, combined with avenues for marketing, promotion and distribution. DE will provide links to developer's websites that create DE modules, and offer incentives and bundling opportunities where appropriate. Already, such companies as STF Technologies have realized the potential of DE's modularity, as evidenced by the fax module suite which accompanies Document Express.

Figure 3. The FAXstf module suite.

A Word of Thanks

At this point I would like to extend a thank you to Mark Teixeira, creator of Document Express. First of all, he asked me to write this article, but he also proved to be an endless source of information, support, and kindness. I complement him on generating a fine product for the Macintosh and having the thoughtfulness to create such a well engineered SDK. Readers who are interested in Document Express should take a look at <http://www.documentexpress.com>, or email <info@documentexpress.com> for further information. Also, be sure to hop over to <http://www.atpm.com> in April (or sooner!!!) for my in depth review of Document Express 2.0.

Why Document Express?

The process of generating an automated, personalized, and intelligent response to a web form is indeed a company's dream solution for automated marketing, support and customer service applications. With this technology, comes a new breed of solutions never before thought possible. Thanks to Document Express, there now exists a tool, an extensible tool, which can accomplish these customized messaging tasks with unprecedented ease and simplicity. DE's large features set, internal email and database engines, and well designed and documented SDK provides both end users and developers with a powerful, flexible, and intuitive tool with which to manage their many methods of communication.

---

Evan Trent (evan@sover.net) is a first year student at the University of Chicago (http://emt.rh.uchicago.edu). He serves as the Reviews Editor and co-webmaster for About This Particular Macintosh (http://www.atpm.com) a free Macintosh e-zine. He has been programming in C/C++ for several years now as a hobby.