toAttachment()

This document definition function generates attachments for text and image resources, and can be used if the output is intended for email delivery.

When the toAttachment() function is called it creates an attachment output stream in which the resource data is sent. It also generates a unique identifier, a cid, associated with the resource data in the output stream. The cid, which is an ordinary string, is returned to the caller. The cid can be used in, for example, <img> and <a> tags to reference the resource data.

Example 51

Using toAttachment()

The following directive creates an attachment output stream for the image resource Im1 and returns a cid associated with the resource data:

#set($r=$docdef.S1.Im1.toAttachment())

In the Template Engine template <img src="$r"/> is used to reference the resource data. The Template Engine output will have the cid as reference, for example:

<img src="cid:57E498EB-8E08-9E46-9FCC-B59CB41280CB"/>

 

Syntax

<resource>.toAttachment([<name>[, <contentType>]])

resource	Reference to a document definition resource.
name	The attachment name. If not specified, the name of the resource is used.
contentType	The content type of the resource, e.g. image/pjpeg. If not specified, the most likely content type is used.

Calling toAttachment() and referencing the attachment

In the Template Engine template you can call the toAttachment() function and reference the corresponding attachment in different ways. Some valid example are illustrated below.

Example 52

Calling toAttachment() and referencing the attachment

<img src="$docdef.S1.I1.toAttachment()"/>

#set($att="$docdef.S1.I1.toAttachment()")
<img src="$att"/>

#set($sec="$docdef.S1")
<img src="$sec.I1.toAttachment()"/>

#set($res="$docdef.S1.I1")
<img src="$res.toAttachment()"/>

#set($array=$docdef.S1.resourceArray())
<img src="$array[1].toAttachment()"/>

 

Attaching resources

If you only declare a variable for the attachment, for example #set($r=$docdef.S1.Text1.toAttachment('Text1.html')), the resource data is added as an attachment to the email. The email recipient must click the attachment to view the content in this case.

Note:

If the attachment name does not have the appropriate extension (e.g. Text1.html) the email client cannot determine which viewer to use.

Using links to reference attachments

If you add an <a> tag to the Template Engine template, the email recipient can click a link to view the content of an attachment. For example:

#set($r=$docdef.S1.T1.toAttachment('Text.html'))
<a href="$r">Link text</a>

Note:

If the attachment name does not have the appropriate extension (e.g. Text1.html) the email client cannot determine which viewer to use.

Displaying attached images in the email body

If the resource is an image resource you can add an <img> tag to the Template Engine template and have the image displayed in the email body. For example:

#set($img1=$docdef.S1.I1.toAttachment())
<img src="$img1"/>

Note:

The attachment name does not have to include a file extension.

Referencing different resources using the same attachment name

If you try to reference different resources using the same attachment name, the cid is associated with the resource you reference first. This means the same resource will be used for both references in the output.

Example 53

Referencing different resources using the same attachment name

Template

#set($abc=$docdef.S1.Dog.toAttachment('Image1'))
<img src="$abc"/>
#set($xyz=$docdef.S1.Cat.toAttachment('Image1'))
<img src="$xyz"/>

Output

<img src="cid:70179CF0-C9A0-5D4D-B4D2-32CFBC5E0639">
<img src="cid:70179CF0-C9A0-5D4D-B4D2-32CFBC5E0639">

 

Attaching external resources

The toAttachment() function is used to attach resources in a document definition to an email. To attach external resources to an email you must use the $attachments.addAttachment function. See $attachments.addAttachment.

Note:

If you use the same attachment name in a toAttachment() function and in an $attachments.addAttachment function, both references will have the same cid.

Examples

Example 54

Attaching a resource

Template

#set($img1=$docdef.S1.I1.toAttachment('Image1.jpg'))
<p>See attachment Image1.jpg.</p>

Output

<p>See attachment Image1.jpg.</p>

Comment

The image data in resource I1 is attached as Image1.jpg to the email. The recipient must click the attachment to view the content.

 

Example 55

Attaching a resource – no resource name specified

Template

#set($img1=$docdef.S1.I1.toAttachment())
<p>See attachment Image1.jpg.</p>

Output

<p>See attachment Image1.jpg.</p>

Comment

The image data in resource I1 is attached as I1 to the email. The recipient must click the attachment and select the appropriate viewer to view the content.

 

Example 56

Adding a link to an attachment

Template

#set($text1=$docdef.S1.T1.toAttachment('Text1.html'))
<p><a href="$text1">See this</a></p>

Output

<p><a href="cid:06474328-D808-B642-B748-E8D294283E49">See this
</a></p>

Comment

The text data in resource T1 is attached as Text1.html to the email. The recipient must click the "See this" link to view the content.

 

Example 57

Adding a link to an attachment – content type specified

Template

#set($text1=$docdef.S1.T1.toAttachment('Text1.html', 'text/html'))
<p><a href="$text1">See this</a></p>

Output

<p><a href="cid:06474328-D808-B642-B748-E8D294283E49">See this
</a></p>

Comment

Same as the previous example, but the content type is added as argument.

 

Example 58

Displaying an image attachment in the email body

Template

#set($img1=$docdef.S1.I1.toAttachment())
<img src="$img1"/>

Output

<img src="cid:6E8D6107-90E2-6E41-99BF-308E7E93C2FA">

Comment

The image data in resource I1 is attached as I1 to the email and displayed in the email body.

 

Example 59

Looping over all resources in a section

Template

#foreach($r in $docdef.S1.resourceArray())
#set($image=$r.toAttachment('', $r.contentType()))
<img src="$image"/><br/><br/>
#end

Output

<img src="cid:D8AEEF8A-45BF-A348-92C9-510C50B20983"><br><br>
<img src="cid:C7125184-FEF5-344F-B47D-388B38A23938"><br><br>
<img src="cid:4125B4C4-977B-FD4D-817B-4A4D475B758F"><br><br>

Comment

The image data in all resources in section S1 are attached to the email and displayed in the email body. Content type argument specified but not name argument.