© 1999 GreyTrout Software, Inc.
Permission is hereby granted to use and/or modify this program for any purpose so long as this copyright notice remains unaltered. GreyTrout Software, Inc. makes this software freely available in hopes that it will be useful, but does not claim that it is free of errors or suitable for any purpose.
The NExS Data Mailer (ndm) is an example application demonstrating the use of the tclNExS API to build an application using Tcl/Tk and the NExS spreadsheet. This is a "mail merge" application which provides a simple text editor for composing e-mail messages to a list of recipients whose addresses are contained in a row or column of the spreadsheet. Data related to the individual recipients is extracted from the spreadsheet and inserted in the message. This would be useful, for example, for e-mailing grade information to each student in a class where a NExS spreadsheet was used to store and tabulate the grades.
As an extension to the basic "mail merge" functionality, a "condition" field is provided. The conditional expression can be used to limit the recipients of the e-mail message to those who meet a certain criteria. To continue the student grade example, this function could be used to send an e-mail to all students whose average after the midterm exam is less than 70 percent.
To utilize the NExS Data Mailer, you must have the NExS spreadsheet and the tclNExS package installed. (Both packages can be downloaded from http://www.greytrout.com.) The only setup which is required beyond installing these packages is to edit the first line of the ndm script to point it to the correct location of the tclNExS binary.
The script comes out of the box with the line which actually calls "sendmail" commented out. Instead, it prints the generated email messages to the standard output. I recommend that you try it this way at first so that you don't send unintended e-mails all over the place while you are figuring out how the program works!
Once you have tried the example "grades.msg", uncomment the following line:
# exec echo "$msg" | /usr/lib/sendmail $to_whom
and comment out the two "puts" lines below it.
The best way to learn how this application works is to try the example. There are three data elements in the application: 1) The e-mail message body, 2) the "address range" which specifies the location of the e-mail addresses in the spreadsheet, and 3) the optional "condition" which specifies a condition that must be met for an e-mail message to be sent to a recipient.
Here is how to run the example. (The "$" is the shell prompt):
$ nexs -con a grades.xs3 & $ ndm grades.msg &
At this point the "grades" spreadsheet should be up on your screen, as well as the NExS Data Mailer main window. Notice that the "address range" (b4..b8) corresponds to the location of the e-mail addresses of the students in the spreadsheet. There is no "condition" expression because we want to send the e-mail to all the students. In the text window of the data mailer, you see the body of the e-mail message, which contains plain text with embedded tags that look like "<c*>" and such. These tags are spreadsheet cell addresses from which data in the spreadsheet will be extracted and inserted in the e-mail message. The "*" is a "wildcard" which in this case means "the current row". When the data mailer is iterating through the address range, row or column values which are specifed as "*" will equate to the current cell being processed in the address range.
The "Address Range" specifies the location of the list of e-mail addresses in the spreadsheet, which may be either a row or a column. In the grades.xs3 spreadsheet, the e-mail addresses of the students are located in cells B4 through B8, hence the "address range" is set to "b4..b8" (case is insignificant here). The grades for Quiz 1 are located in column C. Therefore, to tell the NExS data mailer to substitute the Quiz 1 grade in the e-mail message it is constructing, the proper tag to store in the message is "<c*>".
To see the effects of substituting the spreadsheet cell data into the e-mail message, click the "Preview" button. This will pop up a window containing the message that would be generated for the first address in the list. In the case of our example, the grades for Tim Taylor will be displayed. If the formatting or data in the message is not what you expect, recheck and correct the text in the message window.
Once you are ready to send the e-mail messages, click "Send". This will cause the NExS data mailer to iterate through the "Address Range", generate the e-mail messages and send them to the recipients. (This may take a while for long lists!)
The "Condition" expression is not used in this example, but provides a powerful extension to the NExS Data Mailer. This expression is any valid spreadsheet boolean formula which is checked on each address iteration. If the expression evaluates "true" (non-zero), then the e-mail message is generated and sent. If it evaluates "false" (zero) no message is sent and the mailer proceeds to the next address. For example, setting the condition to "<e*> < 70" could be used to send a notice to each student who made less than a C on the midterm exam.
The "Open" button on the NExS Data Mailer invokes a file selection dialog prompting you to select a ".msg" file. When the file is opened its contents are loaded in the NExS Data Mailer where it can be edited and used to generate e-mail messages. The "Save" button invokes a file save dialog, allowing you to save your ".msg" file.
The NExS Data Mailer uses a simple ASCII file format. The first line of the file specifies the "Address Range" value. The second line specifies the "Condition", if any. The remainder of the file contains the message text.
Most error checking is left to the Tcl interpreter, so expect to see "stack trace" popups if you try to load an improper message file or something like that. On some platforms you may get a core dump if you try to start ndm before you start "nexs -con a". This is a bug in the tclNExS interpreter that will be corrected in the next release.© 1999-2003 GreyTrout Software, Inc. All Rights Reserved