Dynamically adding sections (cloning)

This topic explains how to clone a section in a Control Script, Print sections can be cloned, so that a document can have a dynamic number of sections, based on data. This is particularly useful when the record set defines one or more PDFs (e.g. insurance policies) per recipient. Via a Control Script, for each PDF a section can be cloned and each clone can be given one of the PDFs as background (see Control Script: Setting a Print section's background). For each page in the PDF, a page will be added to the section.

For information about Control Scripts in general, see Control Scripts and Control Script API. If you don't know how to write scripts, see Writing your own scripts.

Cloning a section

To clone a section, first use the clone() function and then add the clone to the Print context before or after a specific section, using addAfter() or addBefore():

var printSections = merge.template.contexts.PRINT.sections;
var clone = printSections["Section 1"].clone();
printSections["Section 1"].addAfter(clone);

Cloned sections have the same properties as normal sections, but they cannot call section functions.

Due to resource constraints, the number of unique clones that can be created throughout a job is limited to around 20. A clone is considered unique if it has a different name. This is a rough estimate; if the template is simple, up to 60 clones may be created.
The limit only applies to the amount of unique clones. There is no limit to the amount of clone() function calls.

Renaming a clone

By default, clones receive the name of their source section with a "Clone {sequence}" suffix, for example:
Source: "Section 1"
Clone Name: "Section 1 Clone 1"

Use the name property to assign the cloned section another name, for example:

clone.name = "my_section_clone";

The section name must be unique within the scope of a single record.

It is recommended not to use a random value or a time stamp in the name of a section. Although section names must be unique within the scope of a record, across records it is advisable to keep using the same name for the same clone, to avoid hitting the limit of the number of unique clones that can be created throughout a job (see the previous note).

Targeting elements in a cloned section

As each clone receives a unique section name, one could use CSS style sheets (see Styling and formatting) and personalization scripts (see Variable Data and Writing your own scripts) to further personalize the cloned sections.

The following CSS style rules target the <h1> element in a number of clones and assigns the respective text a different color:

[section="my_section_clone_0"] h1 { color: red; }
[section="my_section_clone_1"] h1 { color: green; }
[section="my_section_clone_2"] h1 { color: blue; }

The same selectors could be used in personalization scripts:

Selector: [section="my_section_clone_0"] h1
Script: results.css('color','red');

In a template script, cloned sections can be found using merge.section:

if (merge.section == "my_section_clone_0") {
	results.html("Clone!");
} else {
	results.html("Original.");
}

Note that in a Control Script, merge.section is only defined when the output channel is WEB; see merge.

Examples

Cloning a section based on the number of records in a detail table

This script creates as many clones of a section as there are records in a detail table. It assigns the new sections a unique name.

var printSections = merge.template.contexts.PRINT.sections;
var numClones = record.tables['detail'].length;
for( var i = 0; i < numClones; i++){
	var clone = printSections["Section 1"].clone();
	clone.name = "my_section_clone_" + i;
	printSections["Section 1"].addAfter(clone);
}
Cloning a section based on data and assigning a background PDF

This script clones a section based on data fields. It disables the source section first and then calls the addPolicy function. addPolicy clones the section, renames it and sets a PDF from the resources as its background. It explicitly enables the clone and then adds it to the Print context.

var printSections = merge.template.contexts.PRINT.sections;
merge.template.contexts.PRINT.sections["Policy"].enabled = false;
if(record.fields.policy_a == 1) {
	addPolicy('a');
}
if(record.fields.policy_b == 1) {
	addPolicy('b');
}
function addPolicy(policy){
	var resourceUrl = 'images/policy-' + policy + '.pdf';
	var clone = printSections["Policy"].clone();
	clone.name = "policy_" + policy;
	clone.background.url = resourceUrl;
	clone.enabled = true;
	printSections["Policy"].addAfter(clone);
}
  
  • Last Topic Update: 07, November, 2017 05:51 AM
  • Last Published: 23, May, 2019 01:55 PM