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 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 clones that can be created is limited to around 20. This is a rough estimate. If the template is simple and the number of clones that has to be made is the same for each record, up to 60 clones may be created.

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 thename property to assign the cloned section another name, for example:

clone.name = "my_section_clone";

Note that section names must be unique.

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: 06:15 AM Mar-07-2017
  • Last Published: 2019-05-22 : 2:52 PM