Download iForm

Topics*

Overview

(top)

iForm processes HTML form submissions. You can use iForm as an alternative to other scripting methods, such as PHP. Since iForm contains an integrated web server it does not require a web server to function. This tour discusses an iForm application which builds an email list in Apple's Address Book when a user submits a form requesting their name and email. The serving of the form, as well as its processing, is handled completely by iForm.

Although a knowledge of AppleScript is not required to use iForm a basic understanding of it is useful. AppleScript is a widely adopted standard scripting language on the Macintosh that enables programs to communicate with each other. The sample example below illustrates this using Apple's Address Book program.

A very good reference on AppleScript is on Apple's web site: AppleScript: The Language of Automation

JumpStart Overview

(top)

In addition to the online reference manual (accessible from the Help menu), and this Tour, the JumpStart is a series of projects that you can use for additional hands-on experience using iForm. They range from simple (Project 0) to advanced (Project 4), and illustrate many additional uses of templates and AppleScript.

The first time you run iForm you will be asked if you want to install the JumpStart. If you choose not to install you can use the "Install JumpStart" command in the Help menu to do so at a later time. The location of installation is always the "Document Root" folder, the folder iForm serves from. The Document Root defaults to a folder named "iForm" inside the "Sites" folder of your Home folder. You can change it using Preferences.

Installation

(top)

After the iForm software archive is downloaded and mounted drag the iForm application to your preferred folder, such as the Applications folder. Then launch the application by double clicking on its icon in the Finder. You should run iForm on a computer with a static IP address, and preferably a registered domain name, so that users can connect.

If you register iForm you will obtain a permanent password which entitles you to all future updates of the product. To register you just need to purchase iForm and wait for the registration confirmation to be delivered by email. Enter your password by selecting "Password..." from the iForm menu.

Installing the Tour Sample:

Once iForm is up and running you should install the "Tour Sample," which will place a copy of the files used by this tour into your Document Root folder so that you can run it. To do this simply select "Install Tour Sample" in the Help menu.

Preferences

(top)

iForm should be configured the first time it is run, and certainly before you try any sample projects, including this tour. iForm is configured using the Preferences window. Select "Preferences..." from the iForm menu. Here is an overview of the various settings:

Mail server (top)

Enter the address and port of your SMTP mail server. If your server requires authentication enter your username and password also. (If your server does not require authentication do not enter any values into the username or password fields or else it is very likely mail will not be delivered.) iForm uses your Keychain to save your password for security, so you may be prompted for authentication.

Software Update (top)

You can opt to have iForm check for updates to the software on program launch. You can also specify the download directory (which is the same as your Internet downloads folder.)

You can also manually check for software updates periodically using the "Software Update..." command in the iForm menu.

Headers (top)

iForm can optionally include two special headers in all email messages it creates.

(1) The "Disposition-Notification-To" header is a request for a return receipt. This enables you to verify the message was received. Not all mail servers (or mail clients) support this feature, and some are known to reject emails which contain this header.

(2) The "X-Mailer" header is used to identify iForm by name to the mail server and recipients. The default name is "iForm" with the current program version appended. You can specify the name of another mail program to spoof the recipients into thinking another program sent the email. This is sometimes useful if a mail server only accepts mail from a restricted set of mailers.

Logs (top)

You can have iForm write a log of its activity to a console log file. Console logs are stored in Home > Library > Logs and may be viewed with the Console application. Click the View button to open the console log (if it exists.) You can also open the console log using the "Console log..." menu item in the File menu.

iForm will log messages and server requests. If you select verbose console logging iForm will additionally log all commands to the mail server and the server responses. This option is usually useful for identifying problems with communication between iForm and the mail server, so it is not usually selected.

Server (top)

iForm has an integrated web server which can be used to serve your forms and response pages. Specify the port on which you want web browsers to connect to iForm. If you run iForm on the same machine as your primary web server be sure to not select the same port number.

iForm looks for the files it obtains requests for in the "Document Root" folder. This folder is the root relative to which file pathnames will be constructed when processing requests. The folder defaults to a folder named "iForm" inside the "Sites" folder located in your home directory. You can select another folder if you wish.

Advanced (top)

Here you can specify the timeout for network operations and the command iForm will use when saying hello to the mail server. The default values usually work well in almost all cases.

Debugging (top)

When an AppleScript error occurs you can see the script after iForm has expanded any "template tags" it may contain. (Template tags are discussed more later on.) Turn this option on to have iForm prompt you for the location to put the script file.

Another option is to turn off quoted printable encoding facilitating viewing the raw source of email messages generated by iForm.

Sample with Address Book

(top)

This tour's primary objective is to present an application of iForm that builds an email distribution list of cards in Apple's Address Book. Each card's data is obtained by soliciting a person's name and email address on a form. The form will be served by iForm, and the form submission will be processed by iForm. This form processing will involve saving the submitted data into a card of a particular Address Book group using an AppleScript.

Before explaining the sample files a discussion of iForm's basic operation is in order. It is important that you understand what templates and "template tags" are, and also understand the importance of "special template tags" which are used to invoke specific actions by iForm.

Templates and Template Tags

(top)

A template is a text file (plain, HTML or AppleScript) which contains "template tags."

Template tags are one of two things:

  • (1) A form input item name enclosed in curly brackets, as in {lastName}, {firstName} and {emailAddress} or prefixed by a double underscore as in __lastName, __firstName and __emailAddress. (This latter case is used only for AppleScript templates.)

    Tags of this type are used to insert that value of the submitted form item by the same name into the template.

  • (2) A pathname to an AppleScript file enclosed in curly brackets as in {TourSample:SampleABScript.applescript}, the pathname specified relative to the Document Root folder.

    Tags of this type are used to insert the result of the execution of the AppleScript into the template. (The result of an AppleScript is usually the value of the last line in the script.)

Caveat: As hinted above, AppleScripts themselves can also be templates in that they may include template tags of type (1). This is how submitted form values are passed into the script before it is executed. However, in this case remember that the tag is not enclosed in curly brackets, but rather prefixed with a double underscore, as in __lastName, __firstName and __emailAddress. The reason for this is that AppleScript uses the curly bracket to delimit lists.

Special Template Tags

(top)

iForm reserves the name of certain form input items (and their corresponding template tags) to implement special functionality. Such input items are usually included on the form as "hidden" elements which the user can't see (unless they view the HTML source of the form in their web browser.)

The complete list of such template tags is discussed in the online reference manual accessible from the Help menu. The five we use in this sample are discussed here, each included as a hidden input item on our form:

  • iForm_mailTo

    Specifies the recipients of the mail message iForm will generate when the form is submitted. You can separate multiple values with commas (no spaces in between.)

    In this example you must use this element to specify your email address. You must open the form in a text editor and change the email address to your own. (Otherwise I will get your email.)

    
<INPUT TYPE="hidden" NAME="iForm_mailTo"
		VALUE="joe@limit-point.com">

  • iForm_replyTo

    Specifies the reply-to address of the message. You can simply use your own address.

    
<INPUT TYPE="hidden" NAME="iForm_replyTo"
		VALUE="joe@limit-point.com">

  • iForm_subject

    Used to specify the subject of the mail message.

    
<INPUT TYPE="hidden" NAME="iForm_subject"
		VALUE="iForm Sample">

  • iForm_mailTemplatePathname

    Used to specify the pathname of the mail message template file relative to the Document Root. (For historic reasons the path's folders are separated by colons as opposed to forward slash. A future version will fix this.)

    
<INPUT TYPE="hidden" NAME="iForm_mailTemplatePathname"
		VALUE="TourSample:EmailNotice.html">

  • iForm_responseTemplatePathname

    Used to specify the pathname of the response template file relative to the Document Root. (For historic reasons the path's folders are separated by colons as opposed to forward slash. A future version will fix this.)

    
<INPUT TYPE="hidden" NAME="iForm_responseTemplatePathname"
		VALUE="TourSample:ThankYou.html">

The Sample Files

(top)

All the files used by this example are part of the software distribution. Refer to the Installation section above for instructions on how to install them. Here is a list of the four files used, along with a brief description of each:

  • TourSampleForm.html

    This is the HTML form a person will load into their web browser to enter their name and email address for inclusion on the mailing list. When they click this form's submit button the information they enter will be sent to iForm. iForm will then use the submitted data to create a new person card in Address Book.

    This form contains just three text fields. One is for the users first name, and it is labeled "firstName." Similarly there is a form input item named "lastName" and "emailAddress" for the person to enter their last name and email address, resp.

    The values of the text fields will be passed to iForm when the form is submitted, and iForm will then associate the values with the names of the input items. This way the values can be referenced by templates and AppleScripts using template tags.

    This form also contains hidden fields, as discussed above in "Special Template Tags." These hidden elements are used by iForm to send the email message and process the response.

  • ThankYou.html

    This is an HTML template iForm will use to build a client response when the TourSampleForm form is submitted. It acts as confirmation to the client, and also specifies how they can be removed from the mailing list they just joined.

  • EmailNotice.html

    This is the HTML template iForm will use to build an email message which will be sent to you in order to notify you that someone submitted the TourSampleForm form.

    As discussed in more detail below this page is a template so that iForm can display the name and email address of the person who submitted the form.

    This template also includes a very special template tag, namely the one which references the AppleScript which we want to execute to create the new Address Book card:

    {TourSample:SampleABScript.applescript}

  • SampleABScript.applescript

    This is an Applescript which iForm will run to make a new person in Address Book. The person will be added to a group named "Form Submissions" provided a person by the same name does not already exist. The group will be created by the script if it does not already exist.

    The script is executed when iForm processes the EmailNotice template described above because that template has a template tag which references this file.

    The script is fairly straightforward, and like most AppleScripts (almost) reads like a human language paragraph telling Address Book what to do. The key element here is to notice how data is passed into the script using the tags "__firstName", "__lastName" and "__emailAddress." As described more below each such tag corresponds to the TourSampleForm form text field input items named "firstName", "lastName" and "emailAddress," resp. 

    
set __groupName to "Form Submissions"
set __emailLabel to "home" -- "work"

set allowDuplicates to false

tell application "Address Book"
   
   if (group __groupName exists) is not equal to true then
      make new group at beginning of groups 
      	with properties {name:__groupName}
      save addressbook
   end if
   
   set personAdded to false
   
   if (group __groupName exists) then
      
      set personExists to false
      
      if (allowDuplicates is false) then
         set allPeopleSameLastName to every person 
         	whose last name is __lastName
         
         repeat with currentPerson in allPeopleSameLastName
            if the first name of currentPerson is __firstName then
               set personExists to true
            end if
         end repeat
      end if
      
      if personExists is false then
         set thePerson to make new person
         set the first name of thePerson to __firstName
         set the last name of thePerson to __lastName
         tell thePerson
            make new email at beginning of emails 
              with properties {label:__emailLabel, value:__emailAddress}
         end tell
         add thePerson to group __groupName
         set personAdded to true
         save addressbook
      end if
      
   end if
   
   return personAdded
   
end tell

    The last line of the script "return personAdded" will be the value of the script. The script tag will therefore be replaced with either the value "true" or "false."

    Caveat: Make sure that when you save your own AppleScripts you save them as text files, and not as a scripts. The extension should be "applescript" and not "scpt" otherwise iForm will not be able to load and process the script.

Running the Sample

(top)

Follow these steps to run the Tour Sample:

(1) First, make sure the folder "TourSample" is located in iForm's Document Root. You can use the "Document Root" button in the monitor window, or the "Go To Document Root..." menu item under the File menu to find the Document Root folder quickly. Recall, the instructions on installing the TourSample were given in the section named Installation.

(2) Now load the TourSampleForm form into your web browser through iForm, i.e. not as a file. For example, using the information in the monitor window you can construct the URL of the form as follows. Find the fields named "Name" and "Port" and build the URL as:

http://<name>:<port>/TourSample/TourSampleForm.html

where <name> and <port> are the values of the fields named "Name" and "Port." For example, on my machine now I can enter this URL to access the form over my Airport network:

http://10.0.1.6:12345/TourSample/TourSampleForm.html

We also built a menu item into iForm to load the TourSampleForm: select "Open Sample Form" in the Help menu:

(3) To run the sample enter a name and email, then click the "Add To Mailings List..." button. The following actions will take place:

  • A response page saying "thank you" will be returned to you.

  • An Address Book card will be created in the "Form Submissions" group.

  • An email confirmation will be emailed to you.

Check your email to find a confirmation email which should look something like this:

Extending The Sample

(top)

An obvious extension is to provide a mechanism for users to remove themselves from the mailing list automatically.

This will be done using the "Epilogue" and template processing features of Mailings and the ability of iForm to process URL's that contain search arguments.

When Mailings is used to send mail to the Address Book group we created above it can postfix each message with a note explaining how the recipient can remove themselves from the mailing list. The user is instructed to click on an accompanying URL which will be processed by iForm. Using the Mailings template processing mechanism the URL will contain the name and email address of the recipient. When iForm receives the request for the URL it will extract the name and remove the person by the same name from the Address Book group.

Do this as follows:

Launch Mailings and open a new Mailer window. Just for fun use this web page as the message body. Assuming you are using a supported browser click the "Current Web Page" button. Your mailer should look something like this:

First add a preamble as a greeting. Select "Preamble" from the "Open Message Editor..." popup menu, and enter a greeting like that shown here (hint: use the "Insert Mail Tag" popup to insert template tags):

Now create an epilogue in the same way. For the content of the epilogue open the Tour Sample file named "RemoveMeSnippet.html" and copy the section which is commented out, at the top:


This email was sent to: {ToAddress}
We value your privacy. If you would prefer not to 
receive our news and special 
offers in the future, 
<a href="http://10.0.2.2:49529/TourSample/RemoveMe.iform?
firstName={ToNameFirst}&lastName={ToNameLast}&emailAddress={ToAddress}">
you may click here
</a> to unsubscribe.

Your epilogue editor should now look something like this:

Note that the epilogue contains a URL which points to iForm because the extension of the filename, namely "RemoveMe.iform," is ".iform" - of course the IP address and port in the URL should identify your copy of iForm. You can see the IP address (or domain name) and port iForm is running on by looking in the iForm Monitor window:

Also note that the URL contains template tags which will be expanded to the first and last name of the recipient, creating the proper "search arguments" for the URL so iForm knows which person should be deleted from Address Book.

When iForm receives a request for a file whose extension is "iform" it treats the file as a template. That means that iForm will read the file, process any template tags it contains and then send the expanded file back as the response. Open the "RemoveMe.iform" file to see the template tags in use. In particular note that this template has a template tag which references the AppleScript file "DeletePerson.applescript" which is responsible for deleting the person from Address Book.

Open the script "DeletePerson.applescript" in ScriptEditor to see how it works. Note that it also is a template, and in particular it uses the values from the URL, namely "firstName" and "lastName" to find the proper record in AddressBook to delete.

When the user receives the mail message and clicks the "unsubscribe" button iForm will execute the AppleScript referenced by the "RemoveMe.iform" file, replace the tag by the script result and return the page to the user. The user should see a response that looks something like this:

Finally, remember that when you are running your own scripts which contain template tags you can use the Debugging pane of the Preferences window to turn on "script saving" which will output the expanded script file should a script error occur:

To try this extension use the original Tour Sample form to add yourself to the mailing list. Then send the message constructed above using Mailings to the proper Address Book group, and check your email. The link to unsubscribe should be at the bottom. If you click it, and everything goes smoothly, you should be removed from the mailing list in Address Book.

Further Extensions

(top)

This example can be extended and improved in other ways. For example:

1) Support other Address Book fields such as address, phone and notes.

2) Use the methods explained in the JumpStart tutorial to handle "required items" in case the user leaves a field blank.

3) The sample script above only creates "home" email addresses. Try adding a popup menu item to the form for the user to specify if the email address is a home or work address, and then use that value to create an email address with the proper label, namely "home" or "work."

Have Fun!

* The display of some images or other user interface items may be different from the current version of the program due to intervening software updates.