Creating a Merge Document

As mentioned previously, Rock currently supports two different merge document formats: HTML and Word. Below we cover how to create a merge document for each format.

Word

The most common document format is Word. Creating these documents is actually pretty simple. Before we jump in it's important to talk about the two strategies for merging using Word.

The first strategy is to create a Word document where the whole document acts as a template for each record. This is most common for things like letters.

Sample Merge Letter Template

With this type of document, you can simply open Word, type your letter and then add in the Lava where you want the dynamic text to show.

You have access to several Lava functions in Word. So, things like {{ 'Now' | Date:' MMMM d, yyyy ' }} will add the current date and time. You can also print data using the "Row" format, as in {{ Row.NickName }}. That pattern should get you most of what you need. You can additionally add in variables (like {% assign now = 'Now' | Date %}) and then print those variables. All of the Lava tags work except ifraw, and lava, while none of the Lava commands or Lava Shortcodes will work.

The second merge document strategy is for occasions when you want more than one record to be displayed on a single page. This is often the case for tasks like creating mailing labels. When creating these types of documents add a {% Next %} code to move to the next record in the list.

Sample Label Merge Template

Rock will automatically figure out what strategy your document is using so there's no extra configuration.

HTML

You might be wondering, "Why would I ever want to use HTML for a merge document?" At first blush it does seem a little odd. HTML, however, is a great tool for incorporating rich media into a format that can easily be printed. It’s often the best choice when you need to print a report that requires showing maps (easy to display using Google's static map API) or person photos (links to their photo in Rock).

Below is a quick example of some HTML/Lava that will present a list of people with their photos (this assumes that the merge document is passed a list of people).

Output of HTML Template

1   <html>
2       <head>
3   		<title>Group Roster</title>
4   		<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/css/bootstrap.min.css">
5    	</head>
6    	
7    	<body>
8    	    <div class="container" style="margin-top: 100px">
9    			<div class="row">
10    			    
11    				{% for row in Rows %}
12    					<div class="col-xs-6 clearfix" style="margin-bottom: 24px; min-height: 200px;">
13   						<div class="pull-left" style="margin-right: 24px; width:20%;">
14    							<img src="{{ 'Global' | Attribute:'PublicApplicationRoot' }}{{ row.PhotoUrl }}" style="width: 100%; border-radius: 100px;" />
15    						</div>
16    						<div class="pull-left">
17    							<h1>{{ row.FullName }}</h1>
18    							{{ row.Email }} <br />
19    							{% for phone in row.PhoneNumbers %}
20    								{{ phone.NumberFormatted }} <small>{{ phone.NumberTypeValue.Value }}</small> <br />
21    							{% endfor %}
22    						</div>
23   					</div>
24    				{% endfor %}
25    				
26    			</div>
27    		</div>
28    	</body>
29  </html>

Note a few things in the code:

  • Line 4: We link out to a hosted version of the Bootstrap CSS file. This provides an easy way to get a default set of styles.
  • Line 11: Now we simply run through each of the rows that were passed to us.
  • Line 14: Inserting a photo is simple! The PhotoUrl property for a person even returns a generic image if the person doesn’t have a photo.

As you can see, creating HTML merge documents is easy. Here are a few additional tips:

  • Adding map images to your merge documents is also fairly simple. Use the following links for more information:
  • HTML merge documents are usually printed. While most people think of HTML as an online-only file format, it actually does have several print capabilities like page breaks. Here are a few links to point you in the right direction:

Note

Cloud Flare
Enabling Scrape Shield with Cloud Flare will block email addresses in HTML merge documents. If you're using this service, it will need to be disabled.