A Set to Launch a Thousand Scripts
Part 1 of 2
By Lorne Walton (walton@bc.sympatico.ca)
BONUS FILE: TROIPLG1.FP3
PLATFORM: Macintosh & Windows
Peter Baanen of Troi Autmatisering is one of the most prolific plug-in developers in the world. His plug-ins include excellent sample files and limited documentation. Here's a list of the plug-ins, along with Mr. Baanen's own descriptions. I will not be able to review the video frame grabber, since I don't have video capability. This article will look at the first four listed below, and an accompanying article will review the latter four.
Troi's web site is <http://www.troi.com/> and you can download 30-day free trial versions of the plug-ins from there. Since the following plug-ins are not included with the magazine, you will need to download them in order to mess around with them.
Troi Coding Plug-in (latest version 1.1.1 , July 17, 1998): $20:
This FileMaker Pro 4.0 plug-in adds Field Encryption: encrypt and decrypt fields using DES encryption technique.
Troi Dialog Plug-in (latest version 1.2.1, September 21, 1998): $20:
This FileMaker Pro 4.0 plug-in adds dynamic dialogs functions to FileMaker Pro 4.0. With it you create dynamic dialog text (and buttons!) and on the fly progress bars.
Troi File Plug-in (latest version 1.2.1 , January 10, 1999): $20:
This FileMaker Pro 4.0 plug-in adds File Manipulation: save or read a field from or to a file. Other manipulations are also possible.
Troi Grabber Plug-in (latest version 1.0, November 9, 1998) $79:
This plug-in adds Video Image Grabbing functions. With it you can take a picture from a video camera and put it into a container field. (Windows version projected for mid-February 1999 appeared to be unavailable still at end of Feb.)
Troi Graphic Plug-in (latest version 1.0, October 28, 1998): $49:
This FileMaker Pro 4.0 plug-in adds color container creation, screen shot capture and making of thumbnails.
Troi Number Plug-in (latest version 1.0, July 4, 1998): $15:
Adds Dynamic Balance Functions to FileMaker 4.0.
Troi Text Plug-in (latest version 1.2.2, January 27, 1999): $17:
Adds SumText, AndText and XORText, UniqueLines and more functions to FileMaker 4.0. See the Charting Plug-in review in this same issue for a way to utilize this plug-in right now.
Troi Serial Plug-in (latest version 1.0,February 23, 1999): $65: Adds Functions that can read and write to all the Serial Ports on a computer. This product was still in Beta at the time this article was written.
Note that special pricing is available of $40 for users who wish to license the first 3 plug-ins listed. Also, Mr. Baanen makes site licenses and developer licenses available. Check out his site.
How Do I Use It?
The procedure of dropping each plug-in into the FileMaker Extensions ("System" if you use a Windows machine) folder and then relaunching FileMaker Pro 4.x, is standard. A flash dialog shows on the screen when a non-registered user calls upon the plug-in, "Please pay the license fee after 30 days;" this disappears after payment of the fee and following a registration algorithm. The syntax for ensuring the user has the plug-ins active is familiar:
If (Left (External ("TrCo-Version"; ""), 19) <> "Troi Coding Plug-in")
Show Message ("Troi Coding plug-in is not installed!")
End If
The version number of the plug-in may be ascertained via:
Right (External("TrCo-Version"; ""))
Troi Coding Plug-in
Continuing on with the Troi Coding Plug-in, we find that 8 more (other than "version") commands have been added:
External ("Troi-Rotate13"; parameter)
External ("Troi-Encrypt"; parameter)
External ("Troi-Decrypt"; parameter)
External ("Troi-Set Crypt Key"; parameter)
External ("Troi-TextSignature"; parameter)
External ("Troi-Checksum"; parameter)
External ("Troi-NumToBinary"; parameter)
External ("Troi-BinaryToNum"; parameter)
Using a combination of these commands, the Coding Plug-in can encrypt & decrypt your sensitive data using a "key" of your (or your user's) choosing. Rotate13 performs a simple 13-place rotation of alphabetic characters:
Set Field (TextField, External ("Troi-Rotate13"; TextField)
Encrypt & Decrypt employ the DES technique and the 6-or-more character, case-sensitive key passed via the Set Crypt Key command, to hide your sensitive text. Don't forget your key! The example file from Troi suggests including a "hint" field that may remind "Mr. User" of the key.
The next two commands create a checksum (ASCII sum mod 1024) or a text signature, which can help detect whether the contents of a field have been changed. The signature is low-ASCII format and may therefore be sent onto the Internet. NumToBinary and BinaryToNum translate numbers between the base 10 and binary representations. In the BONUS file, these calculations are performed via calculation fields overlaid on data entry fields. Note that you have to EXIT all fields for the calculated result to appear; and that any nonzero, non-one digits entered into the binary entry field are ignored.
Late-Breaking News: just as this article was going to press, Troi released v1.1.4 of the Coding Plug-In. The added feature is built-in registration: "We've added a built-in 'register function' intended for database (solution) developers that make shrink-wrap databases. This makes distribution of databases easier."
Troi Dialog Plug-in
Via these commands, the dialog plug-in adds the functions you've always wanted in FileMaker Pro message dialogs:
External ("TrDl-Version"; parameter)
External ("TrDl-DoDialog"; parameter)
External ("TrDl-DoFlashDialog"; parameter)
External ("TrDl-ProgressBar"; parameter)
External ("TrDl-DelayTicks"; parameter)
External ("Troi-Set Separator Once"; parameter)
External ("Troi-Set Default Separator"; parameter)
External ("Troi-DoDialog"; parameter)
The last command is the old name for the DoDialog command, for backward compatibility's sake. DoDialog's parameter takes the form:
prompt|button1|button2|button3|button4|switches
for example, this string, when used as "parameter":
"Print on what size paper?|Letter|Legal||Cancel"
will cause DoDialog to mimic the FileMaker Show Message script step, except that a wide space will appear between the Legal and Cancel buttons, due to null entry for "button3". The optional switches parameter may be set to "input" for a data entry dialog, or "password" to display a password input dialog. The call to DoDialog with the input parameter returns a result equal to the number (from 1-4) of the button that was pressed, followed by "|" and then the text entered. Thus:
Set Field (Username, External ("TrDl-DoDialog"; "Type your name:|OK|||Cancel|Input"))
If (Left (Username, 1) = 4
Set Field (Username, "")
Else
Set Field (Username, Right (Username, Length (Username) - 2))
End if
displays a text entry dialog and sets the value of the text field Username to the entered text if the "OK" button was pressed, and to "empty" if the "Cancel" button was pressed. Of course a default text string may be specified using an optional 7th parameter, as in:
External("TrDl-DoDialog";"Your name:|OK|||Cancel|Input|" & OldName)
The Set Separator commands change the "|" separator to any other character string, e.g.:
External ("Troi-Set Default Separator"; "¶¶")
This is useful when the "pipe" character must appear in your parameter string.
DoFlashDialog displays a dialog that cancels itself after an interval specified in ticks (1/60 second.) A variety of mouse & keyboard activities can allow the user to abort prematurely or to sustain the dialog on-screen longer. This:
External ("TrDl-DoFlashDialog"; "600|You entered the wrong password!")
will display for 10 seconds, then disappear. It will vanish sooner if the mouse button is clicked, and endure longer if the space bar is held.
Progress bars! The following syntax:
External ("TrDl-ProgressBar"; "show|10|dialogtext")
Set Field (gCtr, 1)
Loop
External ("TrDl-ProgressBar"; "incr|1|dialogtext")
Set Field (gCtr, gCtr+1)
Exit Loop If (gCtr > 10)
End if
External ("TrDl-ProgressBar"; "stop")
will show, increment ten times, and remove a progress bar while a time-consuming process goes forward within the loop. If zero is specified as "maxval", then an indeterminate progress bar (barber pole style) is displayed. Very nice!
DelayTicks causes a pause, measured again in sixtieths of a second:
External ("TrDl-DelayTicks"; "15")
causes a quarter-second delay. Great for slowing down the progress of a loop like the progress bar loop above.
In the BONUS file, among other items, you'll find a demo of a two-field data entry input dialog, which could be used for entry of first & last name, name & email address, username & password... but it's obviously meant for name/password, since "bullets" are displayed for the second parameter. The result of the function call is the number of the chosen button, the first text string, then the second text string, separated by that ubiquitous "pipe" character.
Of course, human interface considerations dictate that when using the Troi Dialog Plug-in, your scripts check that the plug-in is present before calling it, and take alternative action if it is not available. Something like:
If (Left(External("TrDl-Version"; ""), 19 = "Troi Dialog Plug-in"))
Set Field (gText, "External ("TrDl-DoDialog"; "Did you enter your name correctly, " & gFullName & "?|Yes|Re-enter||Ignore")"
If (Left(gText, 1) = "2")
Perform Script (Subscripts, "Enter Name")
End If
Else
Show Message ("Did you enter your name correctly?")
If (Status(CurrentMessageChoice) = 2
Perform Script (Subscripts, "Enter Name")
End If
End If
Troi File Plug-in
The amazing list of file manipulation commands allows a file to be created with virtually any attributes, and the attributes of any file type to be inspected:
External ("TrFile-Version"; parameter)
External ("TrFile-ContentsDialog"; parameter)
External ("TrFile-Get FileSpec Dialog"; parameter)
External ("TrFile-GetContents"; parameter)
External ("TrFile-GetFileSize"; parameter)
External ("TrFile-GetDataSize"; parameter)
External ("TrFile-GetResForkSize"; parameter) - Mac only
External ("TrFile-GetFileType"; parameter) - Mac only
External ("TrFile-GetFileCreator"; parameter) - Mac only
External ("TrFile-GetDateCreated"; parameter)
External ("TrFile-GetTimeCreated"; parameter)
External ("TrFile-GetDateTimeCreated"; parameter)
External ("TrFile-GetDateTimeCreated"; parameter)
External ("TrFile-GetDateModified"; parameter)
External ("TrFile-GetTimeModified"; parameter)
External ("TrFile-GetDateTimeModified"; parameter)
External ("TrFile-Save FileSpec Dialog"; parameter)
External ("TrFile-CreateFile"; parameter)
External ("TrFile-SetContents"; parameter)
External ("TrFile-AppendContents"; parameter)
External ("TrFile-DeleteFile"; parameter)
External ("TrFile-CopyFile"; parameter)
External ("TrFile-MoveFile"; parameter)
External ("TrFile-Launch"; parameter)
External ("TrFile-SetDefaultFileSpec"; parameter)
External ("TrFile-SetDefaultCreator"; parameter)
External ("TrFile-SetDefaultType"; parameter)
External ("TrFile-FileSpec To FullPath"; parameter) - Mac only
External ("TrFile-FullPath To FileSpec"; parameter) - Mac only
External ("TrFile-CreateFolder"; parameter)
External ("TrFile-FindFolder"; parameter) - Mac only
External ("TrFile-ListFolder"; parameter)
External ("Troi-Set Separator Once"; parameter)
External ("Troi-Set Default Separator"; parameter)
External ("TrFile-Search"; parameter)
If reading that list of function names doesn't give you some ideas, then you're just not "into" file manipulation. Get File Spec Dialog displays a Standard File dialog and allows a file to be selected. Calling the GetContents function with parameter returned by the Get File Spec command places the contents of the chosen file into a text field. The following steps are equivalent:
External ("TrFile-GetContents"; External ("TrFile-Get FileSpec Dialog"; "Choose a file:"))
and
External ("TrFile-ContentsDialog"; "Choose a file:")
For those people who are always asking how to import a Eudora email file into FileMaker Pro, here's a good first step. The BONUS file shows how to read such a file into a text field in FileMaker. It is left as a tedious exercise for the reader, how to parse that field into relevant database fields. (Note the FileMaker limitation of 64,000 characters per text field. Fortunately, Mr. Baanen thought of that too: we can do a "partial read" by specifying the starting position in the source file and the number of characters to read, making use also of the GetFileSize command.)
The BONUS example goes on to save the contents of that Eudora file as a simple text file. Note the TrFile-DeleteFile step, which precedes the CreateFile step. It is necessary because Troi File will not replace a file with a new one with the same path & name. On the other hand, it will not cause any problem if a nonexistent file is deleted. You can test the returned error result to see if a file was truly found and deleted, but it makes no difference in the current context.
Troi Grabber Plug-in
The demo of this fourth module looks very cool. It requires a video input into your computer, allows viewing of the video footage in a rectangle on a FileMaker layout. Clicking a button to launch the "grab" command creates a new record and places the grabbed image in a graphic container. Another example shows "student registration" including a photo of the student. The instruction set is:
External ("Grab-Version", parameter)
External ("Grab-Initialise", parameter)
External ("Grab-StartPreview", parameter)
External ("Grab-Stop", parameter)
External ("Grab-ImageToClip", parameter)
External ("Grab-DoSettingsDialog", parameter)
External ("Grab-GetSettings", parameter)
External ("Grab-SetSettings", parameter)
Over All...
A nice touch is the way the documentation is included within each example file for these 3 plug-ins. In some cases, the explanation is a bit sparse, and documentation for some newer functions (e.g. Username & Password dialog) was absent. But the examples are excellent; it was difficult to come up with ways to improve on Peter Baanen's examples for this review. The functions themselves are very complete, and have grown since their original releases, presumably in response to user request. After using these external functions for a while, it would be hard to imagine getting by without them!
Need More?
Perhaps the most complete listing of plug-ins for FileMaker Pro 4.x is to be found at Bev Voth's DIG-FM site, <http://www.pc-mac.com/digfm/fourO/plugs.html>. You may also be interested in signing up for Peter Baanen's FileMaker Plug-ins mailing list by visiting <http://www.troi.com/lists/> and clicking on the appropriate link.
All of my testing for these reviews will take place on a Mac, but almost all plug-ins are now being built with two versions, to run on both platforms. A final caution: as mentioned previously in this series, don't forget to update your FileMaker to 4.0v2 if you're still using 4.0v1. The update is free, and with the older version, plug-ins may not function properly unless all plug-ins in the FileMaker Extensions folder (Mac) or SYSTEM directory (Windows) are turned ON in the Applications Preferences.
## END ##