Document Express Module
Volume Number: 15
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.
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