This document explains the functions of the class `DocumentTemplate` and how to use it. Note that it does not cover every single method with the respective parameters in detail.
== Introduction
A DocumentTemplate is a template for generating individualized documents by filling the placeholders inside the template with data. It supports the following file types and formats:
* txt
* html
* eml
* odt
* docx
* docm
* simple strings
== Usage
=== Creating a new DocumentTemplate instance
The most basic way to create a DocumentTemplate is by simply using the constructor, for example:
[source,js]
----
var myTemplate = new DocumentTemplate(myEncodedHtml, DocumentTemplate.types.HTML);
----
The parameters `pTemplateContent` and `pType` are mandatory, the others are not required for every use case. A new instance of DocumentTemplate can also be created by using these static functions for special situations:
* *DocumentTemplate.fromUpload:* Constructs a template from the given FileUpload object.
* *DocumentTemplate.loadTemplate:* Creates a template from a document stored in the database.
=== Generating a document and filling placeholders
Placeholders can be replaced by invoking the method `.getReplacedContent`. It only takes one parameter `pReplacements` which has to be an object with the placeholder as keys and the replacement data as values, like this:
[source,js]
----
var replacements = {
"{@firstname@}" : "Joseph",
"{@lastname@}" : "Juster"
};
var myContent = myTemplate.getReplacedContent(replacements);
----
It's also possible to use contact data with the functions `.getReplacedContentByContactId` (for a single contactId) and `.getReplacedContentByContactIds` (for multiple contactIds at once). If these functions are used, all placeholders defined in the libraries `Placeholder_lib` and `CustomPlaceholder_lib` are available.
To add extra placeholders that are not necessarily related to the contact, you can put them in the parameter `pAdditionalPlaceholders` which has to be an array of Placeholder objects. For placeholders unrelated to contact data, use these Placeholder types:
* *FIXEDVALUE:* A fixed value that is stored inside the Placeholder object, useful for data that is already available when you define the placeholder (e. g. entity fields).
* *CALLBACKFUNCTION:* A callback-function inside the Placeholder object that returns the replacement value, it will be called with the contactId as first argument. You can use this type to resolve the placeholder depending on the contactId or to avoid unnecessary code execution because the function will only be called if the placeholder is actually used inside the template.
Here's an example for the usage of `pAdditionalPlaceholders`:
[source,js]
----
var getProductCountFn = function (pContactId)
{
... //fancy code
}
var additionalPlaceholders = [
new Placeholder("offercode", Placeholder.types.FIXEDVALUE, vars.get("$field.FullOfferCode"),
new Placeholder("productCount", Placeholder.types.CALLBACKFUNCTION, getProductCountFn)
];
var myContent = myTemplate.getReplacedContentByContactId(vars.get("$field.CONTACTID"), additionalPlaceholders);
----
//TODO: explain subtemplates, serial letters, (bulk-)emails
