LiveCode supports revMail to send e-mail via the local e-mail client. This feature is great for sending text based e-mails without attachments. If you want to add more mailing features in iOS, then you have to use either iphoneComposeMail, iphoneComposeUnicodeMail or iphoneComposeHtmlMail. These commands allow you to send emails in plain text, unicode or HTML. The standard To, Cc, Bcc, Subject, Body and Attachment can be populated. In this lesson we look at the command iphoneComposeHtmlMail to send an HTML e-mail with a number of text attachments.

The first step is to set up the user interface through which we can collect information that is to be sent via e-mail.

We create text entry fields for the To: e-mail addresses, the Cc: e-mail addresses, the Bcc: e-mail addresses, the Subject: line and the message body. We then add a button that tells LiveCode to Launch the e-mail. Finally we create three buttons that attach text smileys to the e-mail.

For demonstration purposes, the fields in the above figure have been populated with values. There is one e-mail address in the To: field and one e-mail address in the Cc: field. It is possible to add further e-mail addresses using comma delimitation. The body contains a number of HTML examples that are rendered and formatted by the e-mail client.

The following code sits under the Launch button. It collects the text data from the entry fields and passes this data and any attachments to iphoneComposeHtmlMail.

# declare the variable that holds the attachments
global gvAttachment
on mouseUp
	# declare the variables that hold the information that is to be included in the e-mail
	local tSubject, tTo, tCCs, tBCCs, tBody
	# test if the current device can send e-mails
	if iphoneCanSendMail () is true then      
		# populate the e-mail variables
		put empty into lvLaunchString
		put the text of field "subjectField" into tSubject
		put the text of field "toField" into tTo
		put the text of field "ccField" into tCCs
		put the text of field "bccField" into tBCCs
		put the text of field "bodyField" into tBody
		# send the e-mail
		iphoneComposeHtmlMail tSubject, tTo, tCCs, tBCCs, tBody, gvAttachment
		answer the result with "Ok"
	else
		answer "Your device cannot be used to send e-mail" with "Ok"
	end if
end mouseUp

An appropriate message is raised if the iOS device running this code does not support e-mail.

The smiley buttons shown in the figure of step Create the Input Fields contain the code listed in this step. Each button provides the text string that is to be attached and the name of the attachment file.

Button Attach :-) contains:

on mouseUp
	# attach the ASCII art smiley
	attachToEmail ":-)", "happy.txt"
end mouseUp

Button Attach :-| contains:

on mouseUp
	# attach the ASCII art smiley
	attachToEmail ":-|", "okay.txt"
end mouseUp

Button Attach :-( contains:

on mouseUp
	# attach the ASCII art smiley
	attachToEmail ":-(", "sad.txt"
end mouseUp

The stack script contains the code listed in this step. This code processes activations of the attachment buttons and creates the relevant attachments. Attachments are created in form of a two dimensional array. Each attachment needs to specify the data, the file name and the type of the data that is stored in the attachment.

# declare the variable that holds the attachments
global gvAttachment
command attachToEmail pAttachmentText, pAttachmentName
	local tNumberOfAttachments
	# allow for multiple attachments by creating an array of arrays
	put the number of elements in gvAttachment into tNumberOfAttachments
	put pAttachmentText into gvAttachment[tNumberOfAttachments + 1]["data"]
	put pAttachmentName into gvAttachment[tNumberOfAttachments + 1]["name"]
	put "text/plain" into gvAttachment[tNumberOfAttachments + 1]["type"]
end attachToEmail

Alternatively, if you were only attaching one item, you could remove the first dimension that indexes each attached item. You can update the code to do this by removing the logic that creates the indexing. Command attachToEmail would then look as follows:

command attachToEmail pAttachmentText, pAttachmentName
	put pAttachmentText into gvAttachment["data"]
	put pAttachmentName into gvAttachment["name"]
	put "text/plain" into gvAttachment["type"]
end attachToEmail

If you use the latter command, rather than the first one, you would only be attaching one smiley to the e-mail. This would be the last one you selected before sending the e-mail. Any previously selected smiles would be replaced by the last one you selected.

This LiveCode window allows you to enter the information you would like to send via e-mail from you iOS device. Notice that the content has not yet been formatted into HTML. This stack is for demonstration purposes and you would most likely write your LiveCode application to populate the HTML for you without displaying it to the user.

After you have entered the HTML you would like to send and selected a number of smileys you would like to include in the e-mail, you can launch the iOS mail client by selecting the Launch button.

We selected one smiley as attachment and then selected Launch. This places all the information from the LiveCode user interface we created earlier into the iOS mail compose window.

You could now update the e-mail content using the standard iOS interface, or you could send the e-mail as it is by selecting the Send button.