Forms, Text Parsing, and email

March 19, 2000
by Pat McClellan

Dear Multimedia Handyman,

I am desiging an Interactive Cd-Rom where the user should be able to fill in a form for subscription, with their appropriate details, and then by clicking a button it should automatically send this form to a specfic e-mail address.

Please could help me to figure out how a form could be made , and then how would this be sent to an e-mail address of my choice, all from the comforts of Director 7?

Ranjit Sagoo

Dear Ranjit,

There are three steps involved in your query: acquiring the form data, parsing the data into a string (for transmission), and sending the email. I don't really need to cover the third task because Zac Belado wrote an excellent Using Director article about sending email from Director. As Zac recommends in that article, the best way to send email is to use the DirectEmail Xtra from DirectXtras. I'd suggest after you read this article, you should review Zac's article.

Acquiring the data is pretty easy. You simply need to set up editable fields or text members on the stage, with labels so that the user will know what goes where. In the demo below, I've named the text castmembers very logical names based on the text to be input: firstname, mi, lastname, address, etc.

A sample movie is available for download in Mac or PC format. This is a D7 movie.

When you lay out the fields in the score, keep in mind that they should go into sequential sprite channel, in the order that the user would normally complete the form. For example, firstname goes in channel 2, mi in channel2, lastname in channel3, address in channel 5, etc. That way, the user can simply TAB between fields. In the text member's properties, set the framing to "fixed", and select "Editable" and "Tab to Next Editable Item".

As the user enters the data, we want to have some control over what gets accepted into the data field, so let's put a behavior on the text sprites which intercept the key input (on keyDown) and only passes through the keys we've decided are acceptable. That handler will look like this:

on keyDown me
  
  if the key = BACKSPACE then
    pass
  else if pValidChars contains the key then
    pass
  end if
  
end keyDown

The property pValidChars is a string of all the acceptable characters we'll accept. That string is entered in the getPropertiesDescriptionList dialog box when you drop the behavior on the sprite. That dialog box also allows you to select the name of the data field that the sprite is holding data for.

When the user hits the SUBMIT button, a command is sent to all the sprites to #storeData. This triggers a handler in the behavior on the text sprites, which creates a property list called gDataList and has each sprite save its datafield name and the current value.

on storeData me
  
  if voidP(gDataList) then 
    gDataList = [:]
  end if
  
  setaProp gDataList, pDataField, pMem.text  
  
end storeData

In the demo above, when you hit the SUBMIT button, it goes to a frame where I've displayed gDataList for you so you can see exactly what's happening. At this point, we've got all the data in a property list. Note that if any of the text submitted contains a quotation mark, a colon, or a bracket, then the syntax of the property list would be screwed up. That's why it's important to specify which characters are acceptable as entry.

Now that the data is in a property list, gDataList, we can do almost anything we want with it. You'd certainly have the option just to mail it off to yourself as is, but what if you wanted the user to see a preview? Or perhaps you want to use some of the data within a text field later in the program. I'll demonstrate some basics of parsing that data into a text display -- and I might as well use the email for this example. NOTE: this is only for Director display; if you're really going to email it, then the data is pulled from the list according to the specifications of the email xtra.

For our example in the demo movie above, I chose to format it with a typical email "header", including "to", "from", and "subject". The to and from lines are created by stringing together (concatenating) some words & punctuation with some author-defined properties (pRecipient and pRecipientEmail) as well as some of the data extracted from gDataList.

on formatEmail me
  toEmail = "<" & pRecipientEmail & ">"
  userName = gDataList.firstName && gDataList.MI ¬
    && gDataList.lastName
  fromEmail = "<" & gDataList.emailAddress & ">"
  
  headerLine1 = "To:" && pRecipient && toEmail & RETURN
  headerLine2 = "From:" &&  userName && fromEmail & RETURN
  headerLine3 = "Subject:" && pSubject & RETURN & RETURN
  
  header = headerLine1 & headerLine2 & headerLine3
  
  bodyString = ""
  
  propCount = gDataList.count
  repeat with i = 1 to propCount
    myProp = gDataList.getPropAt(i)
    myValue = gDataList[myProp]
    myLine = myProp & ":" && myValue
    bodyString = bodyString & myLine & RETURN
  end repeat
  pMem.text = header & bodyString
  
end formatEmail

To link together two words (or strings of characters), you'll use the ampersand: &. To link two words together with a space in between, use two ampersands: &&. You can insert linefeeds with the keyword RETURN (it doesn't have to be in caps, I just do it for my clarity.)

I could have created the header in one, very long line of code. However, it's easier to read and edit if you break the lines up into logical chunks such as headerLine1, headerLine2, and headerLine3, and then hook those smaller chunks up to create the whole header.

For the "body" of the email, I created bodyString with a repeat loop that zips through gDataList, extracting the name and value of each property and appending it onto the end of bodyString. When bodyString is complete, the text of our eMailDisplay cast member is set to header & bodyString.

Text concatenation is a handy skill to have. And if you can combine it with property list mining, then you'll have the power to accomplish a wide variety of tasks. Good luck with your project.

Patrick McClellan is Director Online's co-founder. Pat is Vice President, Managing Director for Jack Morton Worldwide, a global experiential marketing company. He is responsible for the San Francisco office, which helps major technology clients to develop marketing communications programs to reach enterprise and consumer audiences.