Objectif Lune PrintShop Mail Connect - 1.4 Owner's Guide

User Guide

Version:1.4.2

User Guide
Version 1.4.2
Last Revision:2016-06-30

Objectif Lune, Inc.
2030 Pie-IX, Suite 500
Montréal, QC, Canada, H1V 2C8

[phone]

www.objectiflune.com

All trademarks displayed are the property of their respective owners.

© Objectif Lune, Inc. 1994-2016. All rights reserved. No part of this documentation may be
reproduced, transmitted or distributed outside of Objectif Lune Inc. by any means whatsoever
without the express written permission of Objectif Lune Inc. Inc. Objectif Lune Inc. Inc. disclaims
responsibility for any errors and omissions in this documentation and accepts no responsibility
for damages arising from such inconsistencies or their further consequences of any kind.
Objectif Lune Inc. Inc reserves the right to alter the information contained in this documentation
without notice.

Table of Contents

Table of Contents 4

Welcome to PrintShop Mail Connect 1.4.2 7

Icons used in this guide 8

Setup And Configuration 9

System and Hardware Considerations 9

Installation and Activation 15

The Designer 27

API 27

Basic Steps 68

Features 69

Designer User Interface 255

Mark Position Options 335

Additional Text 340

Additional Images 340

Additional Barcodes 341

Additional OMRMarks 341

Additional Text Settings 343

Page 4

Additional Image Settings 344

Barcode Options 345

Standard Barcode Settings 345

Codabar Settings 347

Code 128 Settings 349

Code 39 Settings 351

Additional Datamatrix Settings 353

Additional EAN 128 Settings 355

Additional EAN 13 Settings 356

Additional EAN 8 Settings 358

Additional Interleave 2 of 5 Settings 360

Additional PDF417 Settings 362

Additional QR Code Settings 364

Additional UPC A Settings 366

Additional UPC E Settings 368

Additional OMR Mark Settings 370

Keystore 375

PDF Signature 377

Print Manager 398

Page 5

Print Manager Introduction Video 398

Print Manager usage 398

Print Manager Interface 398

Copyright Information 409

Legal Notices and Acknowledgements 410

Page 6

Welcome to PrintShop Mail Connect

Note

In our continuous effort to facilitate your PrintShop Mail Connect experience, our entire
documentation is being overhauled. Since we are still in the process of restructuring all
this information, expect to see our online help evolve frequently over the next few weeks.
We apologize for any inconvenience, but know we are working hard to improve your
experience as quickly as possible.

Since we are always looking for new ways to make your life easier, we welcome your
questions and comments about our products and documentation. A feedback tool will
soon be at the bottom of each page. In the meantime, shoot us an email at

[e-mail].

1.4.2

PrintShop Mail Connect is a series of four tools designed to optimize and automate customer
communications management. They work together to improve the creation, distribution,
interaction and maintenance of your communications.

The PrintShop Mail Connect Datamapper and Designer is designed to create output for print,
email and the web within a single template and from any data type, including formatted print
streams. Output presets applied outside the design phase make printing device independent.

The Designer has an easy-to-use interface that makes it possible for almost anyone to create
multi-channel output. More advanced users may use native HTML, CSS and JavaScript.

PrintShop Mail Connect also includes a process automation server, called Workflow. It is
capable of servicing response form web pages and email to provide interactive business
communications.

PrintShop Mail Connect can create documents for tablets and mobile devices that run a free
CaptureOnTheGo App. Users with a CaptureOnTheGo subscription can then download
documents to their own devices, interact with them and send the captured data back to
PrintShop Mail for conversion into additional documents or workflows.

Page 7

This online documentation covers PrintShop Mail Connect version 1.4.2.

Note

Complementary information that is not critical, but may help you better use PrintShop Mail
Connect.

Tip

Information that is useful or suggests an easier method.

Technical

Information that may require specific knowledge to understand.

Warning

Information that is potentially critical to using PrintShop Mail Connect. Pay close attention.

Icons used in this guide

Icons are used throughout this guide to point your attention to certain information.

Page 8

Setup And Configuration

Note

Windows XP, Windows 2003 and older versions of Windows are not supported by

This chapter describes the PrintShop Mail Connect installation and the different considerations
that are important in regards to the installation and use of PrintShop Mail Connect.

l "System and Hardware Considerations" below
l "Installation and Activation" on page 15

System and Hardware Considerations

There are a variety of considerations to be aware of. These are documented in the following
pages:

l "System Requirements" below
l "Environment considerations" on the facing page
l "Database Considerations" on page 12
l "Network considerations" on page 13
l "Language and Encoding considerations" on page 13
l "Performance Considerations" on page 13

System Requirements

These are the system requirements for PrintShop Mail Connect 1.4.2

Operating System (64-bit only)

l Microsoft Windows 2008/2008 R2 Server
l Microsoft Windows 2012/2012 R2 Server
l Microsoft Windows Vista
l Microsoft Windows 7
l Microsoft Windows 8.1
l Microsoft Windows 10

Page 9

PrintShop Mail Connect.

Minimum Hardware Requirements

Note

For tips and tricks on performance, see "Performance Considerations" on page 13.

Warning

Copying (duplicating) a Virtual Machine with Connect installed and using both images
simultaneously constitutes an infringement of our End-User License Agreement.

Note

While some VMWare (from VMWare, Inc.) and Microsoft virtual machine environments
are supported, other virtual environments (such as Parallels, Xen and others) are not
supported at this time.

l NTFS Filesystem (FAT32 is not supported)
l CPU Intel Core i7-4770 Haswell (4 Core)
l 8GB RAM (16GB Recommended)
l Disk Space: At least 10GB (20GB recommended)

Environment considerations

Virtual Machine Support

PrintShop Mail Connect supports VMWare Workstation, VMWare Server, VMWare Player,
VMWare ESX, Microsoft Hyper-V and Microsoft Hyper-V/Azure infrastructure environments as
software installed on the Guest operating system. PrintShop Mail Connect does not officially
support VMotion under ESX at the moment.

Page 10

Terminal Server/Service

PrintShop Mail Connect does not support Terminal Server (or Terminal Service) environment
as possible under Windows 2000, 2003 and 2008. This is to say, if Terminal Service is
installed on the server where PrintShop Mail Connect is located, unexpected behaviours may
occur and will not be supported by Objectif Lune Inc.. Furthermore, using PrintShop Mail
Connect in a Terminal Service environment is an infringement of our End-User License
Agreement.

Remote Desktop

Tests have demonstrated that PrintShop Mail Connect can be used through Remote Desktop. It
is however possible that certain combination of OS could cause issues. If problems are
encountered, please contact OLSupport and we will investigate.

PrintShop Mail Connect 1.3 and later have been certified under Remote Desktop.

64-bit Operating Systems

PrintShop Mail Connect is a 64-bit software and can only be installed on 64-bit operating
systems.

Antivirus Considerations

l Antivirus software may slow down processing or cause issues if they are scanning in

temporary folders or those used by PrintShop Mail Connect. Please see KB-002:
Antivirus Exclusions for more information.

l Antivirus software might interfere with installation scripts, notably a vbs script to install

fonts. McAfee, in particular, should be disabled temporarily during installation in order for
MICR fonts to install and the installation to complete successfully.

Windows Search Indexing Service

Tests have concluded that the Windows Search service, used to provide indexing for Windows
Search, can interfere with Connect when installing on a virtual machine. If the installation
hangs during the last steps, it is necessary to completely disable this service during installation.

l Click on Start, Run.

l

Type in services.msc and click OK.

l

Locate the Windows Searchservice and double-click on it.

l

Change the Startup Type to Disable, and click Stop to stop the service.

Page 11

l

Try the installation again.

l

Once completely, you may re-enable the service and start it.

Database Considerations

This page describes the different considerations and pre-requisites for the database back-end
used by PrintShop Mail Connect, whether using the MySQL instance provided by the installer,
or pre-existing instance.

Using the MySQL Instance from the Installer

The MySQL Instance provided in the Installation Wizard is already pre-configured with options
to provide the most stable back-end setup.

These are the specific options that have been changed in our version of "my.ini":

l

max_connections = 200 : PrintShop Mail Connect uses a lot of database connections.
This number ensures that even in high volume environments, enough connections will be
available.

l

max_allowed_packet = 500M : In some implementations, especially when using Capture
OnTheGo, large packet sizes are required to allow transferring binary files. This
substantial packet size maximum setting ensures that the data received by PrintShop Mail
Connect will be able to be stored within the database.

l

character-set-server = utf8 , collation-server = utf8_unicode_ci , default-character­set=utf8 : These indicate database support for UTF-8/Unicode.

Using a pre-existing MySQL Instance

If MySQL server is already installed and you wish to use it, the following should be taken into
consideration:

l The MySQL account must have access to all permissions using the GRANT Command,

including creating databases.

l The database configuration must include the options detailed in the "Using the MySQL

Instance from the Installer" above section.

l The SQL instance must be open to access from other computers. This means the bind-

address option should not be set to 127.0.0.1 or localhost.

Page 12

Network considerations

The following should be taken into consideration in regards to network settings and
communications

l

If a local proxy is configured (in the Internet Explorer Optionsdialog, the option Bypass
proxy server for local addresses must be checked, or some features depending on

local communication will not work.

Language and Encoding considerations

Please note the following considerations:

l

Language:

l PrintShop Mail Connect is currently offered in several languages. These languages

can be switch between via the Preferences dialog. The current languages include:

l English
l French
l German
l Spanish
l Italian
l Portuguese
l Chinese (Simplified)
l Chinese (Traditional)
l Japanese.

The default language is English.
The PrintShop Mail Connect help system (this document) is currently only available
in English.

l

Encoding:

l Issues can sometimes be encountered in menus and templates when running

PrintShop Mail Connect on a non-English operating system. These are due to
encoding issues and will be addressed in a later release.

Performance Considerations

This page is a comprehensive guide to getting the most performance out of PrintShop Mail
Connect as well as a rough guideline to indicate when it's best to upgrade.

Page 13

Performance Analysis Details

In order to get the most out of PrintShop Mail Connect, it is important to determine how best to
maximize performance. The following guidelines will be helpful in extracting the best
performance from PrintShop Mail Connect before looking into hardware upgrades or extra
PrintShop Mail Connect performance packs.

l

RAM Configuration: By default, each instance of the Merge Engine and Weaver Engine
is set to use 640MB of RAM. This means that regardless of speed units, if not enough
memory is available, output speed might not be as expected. Assuming that the machine
itself is not running any other software, the rule of thumb is the following: The total number
of used memory in the machine should be pretty much the maximum available (around
95%).

For each engine, it's necessary to modify the .ini file that controls its JAVA arguments.
Edit as follows:

l For the Merge Engine: see C:\Program Files\Objectif Lune\OL

Connect\MergeEngine\Mergeengine.ini

l For the Weaver Engine: see C:\Program Files\Objectif Lune\OL

Connect\weaverengine\Weaverengine.ini

l The parameters are -Xms640m for the minimum RAM size, -Xmx640m for the

maximum RAM size. Explaining Java arguments is beyond the scope of this
document. Please read references here, here and here for more details (fair
warning: these can get pretty technical!).

l

Template and data mapping optimization: Some functionality offered by the
DataMapper and Designer modules are very useful, and sometimes downright awesome,
but can cause the generation of records and of contents items to slow down due to their
nature. Here are some of them:

l

Loading external and network resources: In Designer, using images, javascript
or css resources located on a slow network or on a slow internet connection will
obviously lead to a loss of speed. While we do our best for caching, a document
with 100,000 records which queries a page that takes 1 second to return a different
image each time will, naturally, slow output generation down by up to 27 hours.

l

External JavaScript Librairies: While loading a single javascript library from the
web is generally very fast (and only done once for the record set), actually running a
script on each generated page can take some time. Because yes, JavaScript will
run for each record, and often take the same time for each record.

l

Inefficient Selectors: Using very precise ID selectors in script wizards can be much
faster than using a text selector, especially on very large documents. (more details
on this in another upcoming page).

Page 14

l

Note

A PDF version of this guide is available for use in offline installations. Click here to

Complex Scripts: Custom scripts with large, complex or non-optimized loops can
lead to slowing down content creation. While it is sometimes difficult to troubleshoot,
there are many resources online to help learn about JavaScript performance and
coding mistakes. Here, here, and here are a few. Note that most resources on the
web are about JavaScript in the browser, but the greatest majority of the tips do,
indeed, apply to scripts in general, wherever they are used.

High-Performance Hardware

The following is suggested when processing speed is important. Before looking into a
Performance Packs to enhance performance, ensure that the below requirements are met.

l

A physical, non-virtualized server. ESX and VMWare servers are great for reducing the
numbers of physical machines in your IT space, but they must share the hardware
between each other. While you can create a virtual machine that seems as powerful as a
physical, it will still be sharing hardware with any other virtual machines, and this will
adversely affect performance.

l

MySQL Database on a separate machine. MySQL's main possible bottleneck is file I/O,
and as such a high-performance setup will require this server to be on a separate
machine, ideally with a high-performance, low-latency hard drive. A Solid State Drive
(SSD) would be recommended.

l

High-Quality 16+ GB Ram. This is especially true when working with many server
instances ("speed units") running in parallel. The more parallel processing, the more
RAM is recommended.

l

4 or 8 physical cores. We're not talking Hyper-Threading here, but physical cores.
Hyper-Threading is great with small applications, but the overhead of "switching"
between the virtual cores, and the fact that, well, they're virtual, means the performance is
much lesser on high-power applications such as OL Connect. In short, a dual-core
processor with Hyper-Threading enabled is not equivalent to a quad-core processor.

Installation and Activation

This section provides detailed information about the installation and activation of PrintShop
Mail Connect 1.4.2.

Page 15

download it.

Where to Obtain the Installers:

Note

From PrintShop Mail Connect Version 1.2 onwards, the new version (1.1.8)of the Update
Client is included by default with all setups.

The installers for PrintShop Mail Connect 1.4.2 can be obtained on DVD or downloaded as
follows:

l If you are a Customer, the installers can be downloaded from the Objectif Lune Web

Activations page: http://www.objectiflune.com/activations

l If you are a Reseller, the installers can be downloaded from the Objectif Lune Partner

Portal: http://extranet.objectiflune.com/

For information on licensing, please see Activating your license.

Installation Pre-Requisites

l Make sure your system meets the System requirements.
l PrintShop Mail Version 1.4.2 can be installed under a regular user account with

Administrator privileges.

l

You must install on an NTFS file system.

l PrintShop Mail requires Microsoft .NET Framework 3.5 already be installed on the target

system.

l As with any JAVA application, the more RAM available, the faster the product will

execute.

Installing PrintShop Mail Connect on Machines without Internet Access

In order to install PrintShop Mail Connect it is necessary for the GoDaddy Root Certificate
Authority to be installed (G2 Certificate) on the host machine and for this to be verified online.
When a machine hosting the installation does not have access to the Internet, the installation
will fail because the verification cannot be performed. To solve this problem you must first

Page 16

ensure that all Windows updates have been installed on the host machine. You then need to

Note

PrintShop Mail Connect requires prior installation of Microsoft .NET Framework 3.5 (please refer
to https://www.microsoft.com/en-us/download/details.aspx?id=21 for more details).

complete the following steps:

1. Go to https://certs.godaddy.com/repository and download the following two certificates to
copy to the offline machine:

l GoDaddy Class 2 Certification Authority Root Certificate - G2 - the file is gdroot-

g2.crt

l GoDaddy Secure Server Certificate (Intermediate Certificate) - G2 - the file is

gdig2.crt

2. Install the certificates: Right mouse click -> Install Certificate, and follow the steps through
the subsequent wizard.

3. Now copy the PrintShop Mail Connect installer to the offline machine and start the
installation as normal

Installation Wizard

Starting the PrintShop Mail Connect installer

The PrintShop Mail Connect installer may be supplied as an ISO image or on a DVD:

l If an ISO image, either burn the ISO onto a DVD or unzip the contents to a folder (keeping

the folder structure)

l If on a DVD, either insert the DVD and initiate the installation from there or copy the

contents to a folder (keeping the folder structure)

Navigate to the PrintShop Mail_Connect_Setup_x64.exe or and double-click on it. After a short
while the Setup Wizard will appear as a guide through the installation steps.

Selecting the required components

After clicking the Next button, the component selection page appears, where the different
components of PrintShop Mail Connect can be selected for installation. Currently, the following
are available:

Page 17

l

PrintShop Mail Connect Designer: The Designer module. It may be used as a
standalone with no other installed modules, but it will not have certain capabilities such
as automation and commingling.

l

Installation Path: This is the location where modules are to be installed.

The installer can also calculate how much disk space is required for installing the selected
components as well as how much space is available:

l

Disk space required: Displays the amount of space required on the disk by the selected
components.

l

Disk space available on drive: Displays the amount of space available for installation on
the drive currently in the Installation Path.

l

Recalculate disk space: Click to re-check available disk space. This is useful if space
has been made available for the installation while the installer was open.

l

Source repository location: Displays the path where the installation files are located.
This can be a local drive, installation media, or a network path.

Selection Confirmation

The next page confirms the installation selections made. Click Next to start the installation
itself.

End User License Agreement

The next page displays the End User License Agreement, which needs to be read and
accepted before clicking Next.

Click Next to start the actual installation process. This process can take several minutes.

Completing the installation

This screen describes a summary of the components that have been installed.

l

Configure Update Check checkbox: This option is enabled by default. It causes the
Product Update Manager to run after the installation is complete. This allows

configuring PrintShop Mail Connect to regularly check for entitled updates.
Note: this checkbox may not be available in the event that an issue was encountered
during the installation.

Page 18

l

Technical

Before activating the software, please wait 5 minutes for the database to initialize. If the
software is activated and the services rebooted too quickly, the database can become
corrupted and require a re-installation.

Show Log... : If an issue was encountered during the installation, click this button to
obtain details. This information can then be provided to Objectif Lune for troubleshooting.

l When ready, click the Finish button to close the installation wizard, and initialize the

Product Update Manager, if it was selected.

The Product Update Manager

If the Configure Update Check option has been selected, the following message will be
displayed after clicking “Finish” in the setup:

Click “Yes” to install or open the Product Update Manager where the frequency with which the
updates can be checked and a proxy server (if required) can be specified.
Note: if the Product Update Manager was already installed by another Objectif Lune
application, it will be updated to the latest version and will retain the settings previously
specified.

Select the desired options and then click OK to query the server and obtain a list of any
updates that are available for your software.

l Note that the Product Update Manager can also be called from the “Objectif Lune Update

Client” option in the Start menu.

l It can be uninstalled via Control Panel | Programs | Programs and Features.

Product Activation

After installation, it is necessary to activate the software. See Activating your license for more
information.

How to Run Connect Installer in Silent Mode

The trigger for the Connect Installer to run in silent mode is a text file with the fixed name
install.properties, which is located either in the same folder as the PrintShop Mail_Connect_
Setup_x86_64.exe or in the unpacked folder of the installer.exe.

Page 19

The file needs to be a properties file with the following line types:

l Comment Lines, starting with # (e.g. # The options to configure an external database)
l Key=Value pairs (e.g. install.product.0 = Connect Designer)

For supported keys, please refer to the next paragraph.

Required and Optional Properties

Here is an example of an install.properties file.

# Verbose logging

logging.verbose = true

# Product selection

install.product.0 = Connect Designer

install.product.1 = Connect Server

# Server settings

server.runas.username = Localadmin

server.runas.password = admin

# Database configuration

database.type = mysql

database.host = 192.168.116.10

database.port = 3308

database.username = root

database.password = admin

database.schema = my_ol

Verbose Logging (Optional)

By default, the Silent Installer will log in the same way as the GUI installer. That means
logging of error and warnings, and certain information during database configuration. A more
verbose logging can be switched on by using logging.verbose = true.

Page 20

Product Selection (Optional)

By default, the Silent Installer will install all products which are visible to the user in the
respective brand (except for the Server Extension, because only Server or Server Extension
can be installed at the same time).

However, it is possible to define the products to be installed using their visible product names,
and using a counter for the install.product property, e.g.

l install.product.0 = Connect Designer
l install.product.1 = Connect Server

Other possible product names are Connect Print Manager, Connect Server Extension and
MySQL Product.

Server / Extension configuration (required if Server / Extension is selected for install)

For both, Server and Server Extension, the user credentials who will be running the Server
service need to be provided:

l server.runas.username
l server.runas.password

Additionally for the Server Extension, some properties to define the Master Server are required:

l server.master.host
l server.master.port
l server.master.authenticate = true_or_false
l server.master.username
l server.master.password

Database configuration

If the MySQL Product is part of the installation, the following properties should be defined:

l database.type = mysql (required)
l database.password (required, needs to match the security rules)
l database.port (optional, the default is 3306. The defined port needs to be available.)

Additional properties are required when the configuration of an external MySQL database is
required (this is the case if a Server product but not MySQL product is installed):

Page 21

l database.host
l database.username

Optionally, the "schema" name can be defined (the default is objectiflune):

database.schema

Activating a License

PrintShop Mail Connect includes 30 day trial periods during which it is not necessary to have a
license for reviewing basic functionality. If a modification to the license if required, such as to
allow an extension to the trial period, or for extra functionality, then a new activation code will
need to be requested.

Obtaining the PrintShop Mail Connect Magic Number

To obtain an activation file the OL™ Magic Number must first be retrieved. The Magic Number
is a machine-specific code that is generated based on the computer's hardware and software
using a top-secret Objectif Lune family recipe. Each physical computer or virtual computer
should have a different Magic Number, thus require a separate license file to be functional.

To get the PrintShop Mail Connect Magic Number, open the PrintShop Mail Connect
Designer application:

l

Open the Start Menu

l

Click on All Programs, then Objectif Lune, then PrintShop Mail Connect

l

Open the PrintShop Mail Connect Designer [version] shortcut.

l When the application opens, if it has never been activated or the activation has expired,

the Software Activation dialog appears:

l

License Information section:

l

Magic Number: Displays the PrintShop Mail Connect Magic Number.

l

Copy to Clipboard: Click to copy the Magic Number to the clipboard. It can
then be pasted in the activation request email using the CTRL+V keyboard
shortcut.

l

Licensed Products section:

l

Name: Displays the name of the application or module relevant to this
activation.

Page 22

l

Serial Number: Displays the activation serial number if the product has been
activated in the past.

l

Expiration Date: Displays the date when the activation will expire (or the
current date if the product is not activated)

l

Web Activations: Click to be taken to the online activation page (not yet
functional).

l

End-User License Agreement (Appears only when loading a license file):

l

License: This box displays the EULA. Please note that this agreement is
legally binding.

l

I agree: Select to accept the EULA. This option must be selected to install the
license.

l

I don't agree: Select if you do not accept the EULA. You cannot install the
license if this option is selected.

l

Load License File: Click to browse to the .olconnectlicense file, once it has been
received.

l

Install License: Click to install the license and activate the software (only available
when a license file is loaded).

l

Close: Click to cancel this dialog. If a license file has been loaded, it will not
automatically be installed.

The Software Activation dialog can also be reached through a shortcut located in All Programs, then

Objectif Lune, then PrintShop Mail Connect and is named Software Activation. Since it does not

load the software, it is faster to access for the initial activation.

Requesting a license

After getting the Magic Number, a license request must be done for PrintShop Mail Connect:

l

Customersmust submit their Magic Number and serial number to Objectif Lune via the
Web Activations page: http://www.objectiflune.com/activations. The OL Customer Care
team will then send the PrintShop Mail Connect license file via email.

l

Resellerscan create an evaluation license via the the Objectif Lune Partner Portal by
following the instructions there: http://extranet.objectiflune.com/

Note that if you do not have a serial number, one will be issued to you by the OL Activations
team.

Page 23

Accepting the license will activate it, after which the PrintShop Mail Connect services will need
to be restarted. Note that in some case the service may not restart on its own. To resolve this
issue, restart the computer, or start the service manually from the computer's Control Panel.

Activating PrintShop Mail Connect

To activate PrintShop Mail Connect, simply save the license file somewhere on your computer
where you can easily find it, such as on your desktop. You can then load the license by double­clicking on it, or through the start menu:

l

Open the Start Menu

l

Click on All Programs, then Objectif Lune, then PrintShop Mail Connect

l

Open the PrintShop Mail Connect Designer [version] shortcut. The “PrintShop Mail
Connect Software Activation” tool displays information about the license and the End-

User License Agreement (EULA).

l

Click the Load License File button.

l Read the EULA and click I agree option to accept it.

l

Click Install License to activate the license. The license will then be registered on the
computer and you will be able to start using the software.

After installation message will appear warning that the Server services will need to be restarted. Just click
OK to proceed.

Migrating to a new computer

Currently there are no special migration tools to move data from one PrintShop Mail Connect
installation to another.
Instructions for migration will be available for later versions of the software when those tools
become available.

User accounts and security

Permissions for PrintShop Mail Connect Designer

PrintShop Mail Connect Designer does not require any special permissions to run besides a
regular program. It does not require administrative rights and only needs permission to
read/write in any folder where Templates are located.

If generating Print output, PrintShop Mail Connect Designer requires permission on the printer
or printer queue to send files.

Page 24

The Importance of User Credentials on Installation and
Running

OL Connect and required credentials depends heavily on the Connect component and
respective tasks and what sort of user credentials are needed.

First of all, it is important to distinguish between installation and run-time

Installation

The Connect installer puts all required files, folders, registry entries and much more to their
correct places and locations. As many of these locations are protected against malicious
accesses, that very user under whose context the Connect installation is started and running,
needs very extensive rights on the respective computer. This user must belong to the Local
Administrators group on that machine. Here are some required capabilities, this user:

l Must be able to write into the "Programs" folder.
l Must be allowed to check for existing certificates and must also be allowed to install new

ones into the global certificate store on that machine.

l Must be able to write into HKLM and any subtree of it in the registry.
l Must be able to INSTALL, START and RUN services and also to MODIFY service

settings.

l Must be known in the network the machine belongs to and must also need to be able to

use shared network resources like shared drives and/or printers etc.

This list may not be complete, but it gives the extent of the requirements. Generally, the local
administrator of the machine will have all these credentials, but there may exist network
restrictions and policies, which will block one or more of these capabilities. In such cases, the
respective network administrator should provide a valid user account for the installation.

User Account

The user account shall be used to later RUN one of the Connect Server flavors (Server or
Server Extension). This dedicated user account has to be entered on the respective installer
dialog page and must be allowed to START, STOP and RUN services on this machine. This is
different from the credentials of the installation user account, which additionally requires the
right to INSTALL services. Please be aware of this fact!

Additionally, the Server user must be able to access any network resources that are required for
OL Connect to function properly. This includes e.g. additional drives, printers, scanners, other

Page 25

computers and, where appropriate, internet resources, URLs, mail servers, FTP servers,
database servers and everything else planned to be used for the intended operation of
Connect. The Server user is the run-time user.

Connect Components

Usually, a standard end user will only be facing Connect Designer and maybe the License
Activation Tool. Designer this does not require administrator rights. Either everything required
to create documents or also to run some tasks will be already available (installed by the
installer) or be accessible in a way, where no specific credentials are required. However some
tasks like starting an email campaign will possibly require a respective account at a mail server.
But this has generally nothing to do with the credentials of the Designer user.

Activation Tool

To run the Software Activation Tool, administrator rights are required because this tool needs to
write the license file in one of the protected folders of Windows. The tool will however allow to
restart it with respective credentials if required.

MySQL

MySQL database service is installed by the install user (thus again the requirement of
installing, starting, running and modifying services). Once running it will just work.

Merge and Weaver Engines

These components do run under the Designer (if only Designer is installed) or the Server /
Extension service(s) and inherit the rights of their parent application.

Server (Extension) Configuration Tool

This component needs to access the settings of the Server. As these are stored and read by the
Server, it should be clear that the user used to run the Configuration tool should be the same as
the Server Service user as explained above.

Page 26

The Designer

The Designer is a WYSIWIG (what you is what you get) editor that lets you create templates for
various output channels: Print, Email and Web. A template may contain designs for multiple
output channels: a letter intended for print and an e-mail variant of the same message, for
example. Content, like the body of the message or letter, can be shared across these contexts.
Templates are personalized using scripts and variable data.More advanced users may use
native HTML, CSS and JavaScript.

The following topics will help to quickly familiarize yourself with the Designer.

l "Basic Steps" on page 68. These are the basic steps for creating and developing a

template.

l "Features" on page 69. These are some of the key features in the Designer.
l "Designer User Interface" on page 255. This section gives an overview of all elements in

the Designer User Interface, like menus, dialogs and panes.

More help can be found here:

l Tutorials On Video: watch an introductory video, overview tutorials or practical how-to

videos.

l Forum: Browse the forum and feel free to ask questions about the use of Connect

software

l Demo site. Download demonstrations of OL products.

...

API

Designer Scripts API

This page describes the different features available in scripts created inside the Scripts pane.
See "Write your own scripts" on page 195.

Features that are only available in Control Scripts are listed in the Control Script API. See
"Control Script API" on page 61.

Page 27

Objects

results The HTML element or set of HTML elements that match the selector

specified in the script editor.

record The current record in the main data set.

logger Global object that allows you to log messages.

locale Defines which locale to use.

"formatter" on
page 51

automation Automation properties

merge Merge properties

Global functions

Skin/Formats/CrossReferencePrintFormat("loadhtml() Global function
thatreplaces the content (inner html) of each matched element in the result
set, alternatively load the data into a variable.The location should be an URL
or a relative file path. loadhtml(location)loadhtml(location, selector) Loadhtml()
iscached per batch run (based on the URL) in print/email. loadhtml(location)
Loads allHTML from the HTML file. locationString containing a path that can
be absolute or relative to the section/context. Use: snippets/<snippet-name> to
retrieve the content from a HTML fileresiding in the Snippets folder on the
Resources panel.ExamplesThis script loads a local HTML snippet (from the

Global object that allows you to format values.

Loads
HTML
data from
aHTML
(snippet).
The
returned
HTML can

be placed
Resources panel) directly into the matched elementsresults.loadhtml
("snippets/snippet.html");The following script loads a local HTML snippet
(Resources panel) into a variableThe replaceWith()command is used to
replace the element(s) matched by the script's selector with the contents of the
snippet.var mysnippet = loadhtml('snippets/snippet.html'); results.replaceWith
(mysnippet);Same result as the previous script, but a different
notation:results.replaceWith(loadhtml('snippets/snippet.html'));The following
script loads a snippet into a variable and finds/replaces text in the variable

into a

variable

or into a

set of

HTML

elements.

Page 28

before inserting the content into the page. The second find command also
adds formatting to the replacing text.var mysnippet = loadhtml
('snippets/snippet.html'); mysnippet.find('@var1@').text('OL Connect 1');
mysnippet.find('@var2@').html('<i>OL Connect 2</i>').css('text­decoration','underline'); results.replaceWith(mysnippet); This last script loads
a snippet into a variable and retrieves an element from the snippet using
query().var mysnippet = loadhtml('snippets/text-root-wrapped.html'); var
subject = query("#subject", mysnippet).text(); results.append("<p style='font­weight: bold;'>" + subject + "</p>");loadhtml(location, selector) Retrieve
specific content from the filename. locationString; the location can be
absolute or relative to the section/context. Use: snippets/<snippet-name> to
retrievethe contentfrom a HTML fileresiding in snippets folder of the
Resources panel.selectorString. The supplied selector should conform to
CSS selector syntaxand allows you to retrieve only the content of matching
elements.ExamplesThis script loads a specific element from the snippet.var
mysnippet = loadhtml('snippets/snippet-selectors.html','#item3');
results.replaceWith(mysnippet);This script loads the children of the selected
element.var snippet = loadhtml('snippets/snippet.html','foobar').children();
results.replaceWith(snippet);Another example is given in the following how-to:
Using a selector to load part of a snippet." on page 1)

"loadjson()" on page 54 Loads

jsondata

from an

url. This is

an simple

way to

retrieve

content

from

external

systems.

"query()" on page 58 Performs

a query in

the

Page 29

template's

contents

and

creates a

new result

set

containing

the HTML

elements

that match

the given

CSS

selector.

Functions

All these functions can be used with an HTML element or a set of HTML, such as the results
(the HTML element or set of HTML elements that match the selector specified in the script
editor) or the result set returned by a query (see "query()" on page 58).

"add()" on
page 32

"addClass()"
on page 33

"after()" on
page 34

"append()" on
page 36

"attr()" on
page 39

"before()" on
page 40

Adds elements to a set of HTML elements.

Adds the specified class to each element in a set of HTML elements.Has
no effect if the class is already present.

Inserts contentafter each element in a set of HTML elements..

Inserts content at the end of eachelement in a set of HTML elements.

Change the given attribute of the element or set of HTML elements with
the given value.

Inserts content before an element or before each element in a set of HTML
elements.

Page 30

"css()" on

Gets the value of a style property for the first element in set of HTML

page 43

"children()"
on page 42

"clone()" on
page 42

filter() Returns a subset of the current result set.

find() Performs a search for a text in the children of each element in a set of

hasClass() Returns true if the first element in this result set has the specified class.

hide() Hides the HTML element or set of HTML elements.

elements or sets one or more CSS properties for every element in a set of
HTML elements.

Returns the immediate children of an HTML element.

Returns a new result set containing a copy of each element in a set of
HTML elements.

HTML elements, and returns a new result set with elements that surround
the occurrences.

html() Replaces the inner HTML of the element or of each element in a set of

HTML elements with the supplied value, or returns the HTML of the first
element if no value is supplied.

is(selector) Returns true if at least one of the elements in a set of HTML elements

matches the supplied CSS selector.

parent() Returns the parents of the elements in a set of HTML elements.

"prepend()"
on page 56

"CopyFile()"
on page 60

removeAttr() Removes the specified attribute from each element in this result set.

"removeClass Removes the specified class from an element or from each element in a

Inserts content at the beginning of an HTML element or of each element in
a set of HTML elements.

Removes an HTML element or a set of HTML elements from the
document.

Page 31

()" on page 60 set of HTML elements. Has no effect if the class is not present.

"replaceWith
()" on page 60

show() Shows the HTML element or a set of HTML elements.

text() Replaces the textcontentof an HTML element or of each element in a set

Examples of iterator functions

"Each" on
page 49

"For...in"
on page 51

add()

Replaces an HTML element or a set of HTML elements (with a snippet, for
example). Returns the result set.

of HTML elements with the supplied value, or returns the text content of
the first element if no value is supplied.

A generic iterator function, to iterate over the elements in the result set

Iterates over the enumerable properties of an object, in arbitrary order. For
each distinct property, statements can be executed.

The add() function allowsyou to add elements to a set of HTML elements that match the
selector of the script or of another query in the template (see "query()" on page 58).

add(content)

Returns the union of this result or result set and other content.

content

A query result. This can be an HTML string or a result set.

Examples

Add one result set to another

This script adds one query result to another and sets the background color to yellow.

query("#test1").add(query("#test2")).css("background", "yellow");

Note: the way the functions add() and css() are used in this script is called 'chaining'. Chaining
is optional; the same could be achieved by storing the results of the queries in a variable:

Page 32

var myResult = query("#test1");
myResult.add(query("#test2");
myResult.css("background", "yellow");

Creating an empty result set and adding elements to it

The following script loads snippets in an iteration and adds their elements to an empty result
set (using query()). Then it replaces a placeholder in the template with the new result.

var chapters = query();
for ( var i = 1; i <= 4; i++) {
chapters = chapters.add(loadhtml('snippets/Chapter' + i +
'.html'));
}
results.replaceWith(chapters);

Selector Matched element Matched element after script execution

#chapters <p id="chapters">{{chapters}}</p> <h1>Chapter 1</h1>

<p>Lorem ipsum...</p>
<h1>Chapter 2</h1>

<p>Loremipsum...</p>
<h1>Chapter 3</h1>

<p>Loremipsum...</p>
<h1>Chapter 4</h1>
<p>Loremipsum...</p>

addClass()

Adds the specified class(es) to each element in a set of HTML elements that match the selector
of the script or of another query in the template (see "query()" on page 58).This has no effect if
the class is already present.

addClass(classname)

Adds the specified class(es) to each element in a result set. Has no effect if the class is already
present.

classname

String, space separated list of class names.

Page 33

Examples

This script adds a class name to a paragraph.

results.addClass("foo");

Selector Matched element Matched element after script execution

p <p>Hello world</p> <p class="foo bar">Hello world</p>

The following script adds two class names to a paragraph.

results.addClass("foo bar");

Selector Matched element Matched element after script execution

p <p>Hello world</p> <p class="foo bar">Hello world</p>

after()

Insert contentafter each element in the set of HTML elements that match the selector of the
script or of another query in the template (see "query()" on page 58).See also: "before()" on
page 40.

after(content)

Insert content after each element in the set of HTML elements that match the selector of the
script, or of another query in the template (see "query()" on page 58).After creates a new result
set.

content

String, HTML string or result set to insert after the matched elements. In case a plain text
string is provided, it is automatically wrapped in a <span> element to avoid orphan text nodes
to appear in the <body> element.

Examples

This script looks up an element with the ID #salesrep and inserts a paragraph after it.

query("#salesrep").after("<p>Lorem ipsum</p>");

Page 34

Matched element Matched element after script execution

<p id="salesrep">Peter Parker</p> <p id="salesrep">Peter Parker</p>

<p>Lorem ipsum</p>

This script looks up an element with the ID #salesrep, sets its text color to red and inserts a
paragraph after it.

query("#salesrep").after("<p>Lorem ipsum</p>").css("color","red");

Matched element Matched element after script execution

<p id="salesrep">Peter Parker</p> <p id="salesrep"style="color: red;">Peter Parker</p>

<p>Lorem ipsum</p>

Note: the way the functions after() and css() are used in this script is called 'chaining'. Chaining
is optional; the same could be achieved by storing the result of the query in a variable:

var salesrep = query("#salesrep");
salesrep.after("<p>Lorem ipsum</p>");
salesrep.css("color","red");

The following script inserts a paragraph after the elements in the results (the set of HTML
elements that match the selector of the script).

results.after("<p>Lorem Ipsum</p>");

Matched element Matched element after script execution

<p id="salesrep">Peter Parker</p> <p id="salesrep">Peter Parker</p>

<p>Lorem ipsum</p>

This script looks for the string "Lorem " in the results (the set of HTML elements that match the
selector of the script).and inserts the string "ipsum" right after that text. The string is
automatically enclosed in a span.

results.find("Lorem ").after("ipsum");

Matched element Matched element after script execution

Page 35

<p>Lorem dolor sit amet,

<p>Lorem<span>ipsum</span>dolor sit amet,

consectetur adipiscing elit.</p>

This script looks up an element with the ID #salesrep and inserts a string after it. The string is
automatically enclosed in a span.

query("#salesrep").after("Lorem Ipsum");

Matched element Matched element after script execution

<p id="salesrep">Peter Parker</p> <p id="salesrep">Peter Parker</p>

append()

Insert contentat the end of each element in the set of each element in a set of HTML elements
that match the selector of the script or of another query in the template (see "query()" on page

58).See also: "prepend()" on page 56.

consectetur adipiscing elit.</p>

<span>Lorem Ipsum</span>

append(content)

Insert content as the last element toeach element in the set of HTML elements that match the
selector of the script or of another query in the template (see "query()" on page 58). Append
creates a new result set.

content

String, HTML string or result set to insert after the elements. In case a plain text string is
provided, it is automatically wrapped in a <span> element to avoid orphan text nodes to
appear in the <body> element.

Examples

This script appends a paragraph to the results (the set of HTML elements that match the
selector of the script).

results.append("<p>Peter Parker</p>");

Page 36

Selector Matched element Matched element after script execution

#box <div id="box">

<h1>Personal information</h1>
</div>

This script appends a string to the results (the HTML elements that match the selector of the
script). The string is added to the end of the matched element(s) and wrapped in a Span
element.

results.append("Peter Parker");

Selector Matched element Matched element after script execution

.name <div>

<h1>Personal
information</h1>
<p
class="name"><b>Name:

<div id="box">

<h1>Personal information</h1>
<p>Peter Parker</p>
</div>

<div>
<h1>Personal information</h1>
<p class="name"><b>Name: </b><span>Peter
Parker</span></p>

</div>
</b></p>
</div>

This script's selector is <div>, so the script appends a paragraph to all Div elements in the
template.

results.append("<p>Peter Parker</p>");

Selector Matched element Matched element after script execution

div <div>

<h1>Personal information</h1>
</div>
<div>
<h1>Personal information</h1>
</div>

<div>
<h1>Personal information</h1>
<p>Peter Parker</p>
</div>
<div>
<h1>Personal information</h1>
<p>Peter Parker</p>
</div>

Page 37

The following script appends a snippet to a Div element with the ID box.

var a = loadhtml('snippets/snippet_name.html');
results.append(a);

Selector

#box

This script looks for an element with the ID box and appends a paragraph to it.

query("#box").append("<p>Peter Parker</p>");

Matched element Matched element after script execution

<div id="box">
<h1>Personal information</h1>
</div>

This script looks for an element with the ID box, appends a paragraph to it and colors all text
inside the box red.

Matched element Matched element after script execution

<div id="box">
<h1>Personal information</h1>
</div>

<div id="box">
<h1>Personal information</h1>
<p>Peter Parker</p>
</div>

<div id="box">
<h1>Personal information</h1>
<p>Peter Parker</p>
</div>

query("#box").append("<p>Peter Parker</p>").css("color","red");

Matched element Matched element after script execution

<div id="box">
<h1>Personal information</h1>
</div>

Note: the way the functions append() and css() are used in this script is called 'chaining'.
Chaining is optional; the same could be achieved by storing the result of the query in a
variable:

<div id="box"style="color:red;">

<h1>Personal information</h1>
<p>Peter Parker</p>
</div>

Page 38

var box = query("#box");
box.append("<p>Peter Parker</p>");
box.css("color","red");

attr()

Returns the value of the specified attribute of the first element in a result set, or sets the value of
the specified attribute of each element in a result set.

l attr(attributeName)
l attr(attributeName, value)

attr(attributeName)

Returns the value of the specified attribute of the first element in a result set.

attributeName

String; the name of the attribute.

Examples

This script - with the selector img - stores the source of the first image in a variable.

var src = results.attr("src");

The following script looks up an element with the ID #table1 and stores its background color in
a variable.

var backgroundcolor = query("#table1").attr("bgcolor");

attr(attributeName, value)

Sets the value of the specified attribute of each element in a result set.

attributeName

String; the name of the attribute.

value

String; value for the attribute.

Page 39

Examples

This script looks up a table cell in an element with the ID #calloutbox and sets its text color to
red.

query("#callout td").attr('bgcolor' , 'red');

The following script sets the background color of a specific table cell to red if the value of the
field TOTAL has a negative value in the current record.

if(record.fields.TOTAL<0) {

query("#total").attr("bgcolor","red");

}

before()

Insert content before each element in the set of HTML elements that match the selector of the
script or of another query in the template (see "query()" on page 58). See also: "after()" on page

34.

before(content)

Before(content) inserts content before each element in the set of elements that match the
script's selector. Before() creates a new result set.

content

String, HTML string or result set to insert after the elements. In case a plain text string is
provided, it is automatically wrapped in a <span> element to avoid orphan text nodes to
appear in the <body> element.

Examples

This script looks for an element with the ID salesrepand inserts a paragraph before that
element.

results.before("<p>Lorem Ipsum</p>");

Selector Matched element Matched element after script

execution

#salesrep

<p id="salesrep">Peter

<p>Lorem ipsum</p>

Parker</p>

<p id="salesrep">Peter Parker</p>

This script does the same, but it uses the query() function to look up the element.

Page 40

query("#salesrep").before("<p>Lorem ipsum</p>");

Matched element Matched element after script execution

<p id="salesrep">Peter Parker</p> <p>Lorem ipsum</p>

<p id="salesrep">Peter Parker</p>

The following script looks for an element with the ID salesrep, inserts a paragraph before that
element and colors that element red.

query("#salesrep").before("<p>Lorem ipsum</p>").css("color","red");

Matched element Matched element after script execution

<p id="salesrep">Peter Parker</p> <p >Lorem ipsum</p>

<p id="salesrep"style="color: red;">Peter Parker</p>

Note: the way the functions before() and css() are used in this script is called 'chaining'.
Chaining is optional; the same could be achieved by storing the result of the query in a
variable:

var salesrep = query("#salesrep");
salesrep.before("<p>Lorem ipsum</p>");
salesrep.css("color","red");

The following script searches the results for the string "ipsum" and puts "Lorem " before it.
"Lorem " is automatically wrapped in a Span element.

results.find("ipsum").before("Lorem ");

Matched element Matched element after script execution

<p>ipsumdolor sit amet, consectetur
adipiscing elit.</p>

The following script looks for an element with the ID salesrep and inserts the text "Lorem
Ipsum" before that element. "Lorem Ipsum" is automatically wrapped in a Span element.

query("#salesrep").before("Lorem Ipsum");

<p><span>Lorem </span>ipsumdolor sit amet,
consectetur adipiscing elit.</p>

Matched element Matched element after script

Page 41

execution

<p>ipsumdolor sit amet, consectetur adipiscing
elit.</p>

<span>Lorem Ipsum</span>
<p id="salesrep">Peter Parker</p>

children()

Returns the immediate children (inner HTML) of the elements in a result set.

Examples

This script retrieves the inner HTML of an element selected from a snippet.

var snippet = loadhtml('snippets/snippet.html','#foobar').children
();
results.append(snippet);

The following script retrieves the inner HTML of the elements and then performs a find/replace.

var snippet = loadhtml('snippets/snippet.html','#foobar').children
();
snippet.find('@firstname@').text('foobar');
results.append(snippet);

clone()

Returns a new result set containing a deep copy of each element in a result set. To duplicate
an existing DOM element, clone it before calling append(); see "append()" on page 36.

Examples

This script performs an iteration over the elements in the results

var row = query("tbody tr", results).clone();
query("tbody", results).append(row);

The following script clones an existing table row to match the number of rows in a detail table.
Afterwards it iterates over the rows to populate the fields.

// Create the number of rows based on the records in the detail
table
// We start at 1 so the boilerplate row is used too and there is no
need to delete that row
for(var r = 1; r < record.tables['detail'].length; r++) {
results.parent().append(results.clone());

Page 42

}

// Iterate over the rows and populate them with the data from the
accompanying data row
query("#table_2 > tbody > tr").each(function(i) {
this.find('@ItemNumber@').text( record.tables['detail'][i].fields
["ItemNumber"]);
this.find('@ItemOrdered@').text( record.tables['detail'][i].fields
["ItemOrdered"]);
this.find('@ItemTotal@').text( record.tables['detail'][i].fields
["ItemTotal"]);
this.find('@ItemDesc@').text( record.tables['detail'][i].fields
["ItemDesc"]);
this.find('@nr@').text(i);
});

The following script clones and populates a boilerplate row. Once completed you will need to
hide the boilerplate row.

css()

Get the value of a style property for the first element in the set of HTML elements that match the
selector of the script or of another query in the template (see "query()" on page 58), or set one or
more CSS properties for every element in the set.

l css(propertyName)
l css(propertyName, value)
l css(properties

css(propertyName)

Returns the value of the specified CSS property.

propertyName

String; the name of the CSS property.

Examples

This script stores the text color of the results (the HTML elements that match the selector of the
script) in a variable.

var textcolor = results.css("color");

Page 43

The following script looks up an element with the ID #calloutbox and stores its background
color in a variable.

var backgroundcolor = query("#calloutbox").css("background-color");

css(propertyName, value)

Function to set a CSS property.

propertyName

String; the name of the CSS property.

value

String; value for the CSS property or a map of property-value pairs to set.

Examples

This script looks up an element with the ID #calloutbox and sets its text color to red.

query("#callout p").css('color' , 'red');

The following script does the same, but it only sets the text color to red if in the current record
the value of the field 'accounttype' is 'PRO'.

if(record.fields.accounttype == "PRO") {
query("#callout p").css("color","red");
}

This script sets the text color of the results to a hexadecimal color code.

results.css('color' , '#669900');

This script loads a snippet into a variable. Then it finds/replaces text in the snippet and applies
a css property to the replacing text.

var mysnippet = loadhtml('snippets/snippet vars.html');
mysnippet.find('@var@').text('OL Connect').css('text­decoration','underline');
results.replaceWith(mysnippet);

css(properties)

Function to set one or multiple CSS properties.

properties

Page 44

Array; map of property-value pairs to set.

Note

The locale also influences the output of the different Date functions; see "Locale" on page 240.

Examples

This script colors the text of the results (the set of HTML elements that match the selector of
the script) red and makes it bold.

results.css({'color' : 'red', 'font-weight' : 'bold'});

Date, date/time and time functions

l date()
l dateLong()
l dateMedium()
l dateShort()
l dateTime()
l dateTimeLong()
l dateTimeMedium()
l dateTimeShort()
l time()
l timeLong()
l timeMedium()
l timeShort()

date(value, pattern)

Formats a date object using a custom pattern.

value

A Date object. A Date can contain a date and time.

pattern

String. The custom pattern may consist of pattern letters, separating symbols and quoted text,
for example: "MMMM dd, yyyy"; see Date and time patterns. Note that the repetition of pattern
letters determines the exact presentation.

Page 45

dateLong(value)

Formats a date as long string representation, for example April 1, 2016.

value

A Date object. A Date can contain a date and time.

dateMedium(value)

Formats a date as medium string representation, for example 01/04/16.

value

A Date object. A Date can contain a date and time.

dateShort(value)

Formats a date as short string representation, for example 1-Apr-2016.

value

A Date object. A Date can contain a date and time.

dateTime(value, pattern)

Formats a date and time object using a custom pattern.

value

A Date object. A Date can contain a date and time.

pattern

String. The custom pattern may consist of pattern letters, separating symbols and quoted text,
for example: "yyyy.MM.dd G 'at' HH:mm:ss z"; see Date and time patterns. Note that the
repetition of pattern letters determines the exact presentation.

dateTimeLong(value)

Formats a date and time as long string representation, for example April 1, 2016 12:00:00 EDT
AM.

value

A Date object. A Date can contain a date and time.

Page 46

dateTimeMedium(value)

Formats a date and time as medium string representation, for example 1-Apr-2016 12:00:00
AM.

value

A Date object. A Date can contain a date and time.

dateTimeShort(value)

Formats a date and time as short string representation, for example 01/04/16 12:00 AM.

value

A Date object. A Date can contain a date and time.

time(value, pattern)

Formats a time using a custom pattern.

value

A Date object. A Date can contain a date and time.

pattern

String. The custom pattern may consist of pattern letters, separating symbols and quoted text,
for example: "'at' HH:mm:ss z"; see Date and time patterns. Note that the repetition of pattern
letters determines the exact presentation.

timeLong(value)

Formats a time as long string representation, for example 12:00:00 EDT AM.

value

A Date object. A Date can contain a date and time.

timeMedium(value)

Formats a time as medium string representation, for example 12:00:00 AM.

value

A Date object. A Date can contain a date and time.

Page 47

timeShort(value)

Note

JavaScript counts months from 0 to 11. January is 0. December is 11.

Formats a time as short string representation, for example 12:00 AM.

value

A Date object. A Date can contain a date and time.

Examples

Creating a Date object from a string

When you open a data file or database in the Designer, all fields are text fields (fields of the
type string). The formatter cannot be used to format a string with a particular date format. The
solution is to store the string in a variable as a Date object, and use the formatter with that
variable.

The following sample script demonstrates this solution. It splits a string into parts and then
creates a new Date object with the parts in the correct order. To construct a Date, the parts of
the date must be put in the following order:year, month, day, and optionally hours, minutes,
seconds, milliseconds (see http://www.w3schools.com/js/js_dates.asp and

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date.)

When the time is omitted, it defaults to 12:00:00 AM.

/* Convert the string 21-12-1997 into a valid JavaScript date */

var strDate = record.fields["date"];
var dateParts = strDate.split("-");
var date = new Date(dateParts[2], (dateParts[1] - 1), dateParts

[0]);

Another way to put a string in a Date is to use the Date.parse function; see

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_
Objects/Date/parse.

The date variable can be used as the value in the date, dateTime or time functions of the

formatter.

var myDate = formatter.date(date, "MM/dd/yyyy");

Page 48

The custom pattern that the script provides, outputs the month and day in two digits each and
the year in four digits: 05/21/2016. For more examples of formatting patterns, see Date and time
patterns.

Each

A generic iterator function, to iterate over the elements in the result set.

each(callback)

Iterates over the elements in a set, such as the enumerable properties of an object, in arbitrary
order. For each distinct property, statements can be executed.

callback

A function. The callback function is passed the iteration index and the current element. In the
scope of the callback function, this refers to the current element.

Examples

The following two scripts demonstrate a simple iteration over the elements in the results (the
set of HTML elements that match the selector of the script).

This script sets the background color of each of the elements to red. (This is just to demonstrate
how this function works. It is easier to change the style of a set of HTML elements using the css
() function; see "css()" on page 43.)

results.each(function(index){

results[index].css('background-color','red');

});

The following script adds a random integer to each element in the result set.

results.each(function(index){

var test = Math.floor((Math.random() * 10) + 1);
this.html(test);

});

Selector Matched

element

p <p></p>

Matched element after script
execution

<p>3</p>

<p></p>

<p>1</p>

Page 49

<p></p> <p>7</p>

This script gets the row index (of the current element in the set) and puts it in a paragraph.

results.each(function(index){

this.text(index);

}

Selector Matched

element

p <p></p>

<p></p>
<p></p>

Using each() in a translation script

The following script first loads a snippet containing translation strings, depending on the value
of a field. Then it inserts translations by iterating over elements in the results (the set of HTML
elements that match the selector of the script) and setting the HTML of each element with a
value from the array of translation strings.

var strings = loadjson('snippets/' + record.fields.locale +
'.html');
results.each(function(index){

if( strings[this.attr('data-translate')])
this.html(strings[this.attr('data-translate')]);

});

Matched element after script
execution

<p>0</p>

<p>1</p>
<p>2</p>

Note: for documentation on the data-* attribute, see http://www.w3schools.com/tags/att_

global_data.asp.

Selector Matched element Matched element after script

execution

p

<p data­translate="first"></p>
<p data­translate="last"></p>
<p data­translate="email"></p>

<p>primero</p>
<p>último</p>
<p>dirección de correo
electrónico</p>

Page 50

For...in

Can be used to iterate over fields in a data set or rows in detail table. Also see

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for...in.

for(variable in object) { ... }

Iterates over the enumerable properties of an object, in arbitrary order. For each distinct
property, statements can be executed.

Examples

This script iterates over field namesin the current record and adds them to a paragraph.

for(var i in record.fields){

results.after("<p>" + i + "</p>");

}

Selector Matched element Matched element after script execution

#test <h1 id="test">Fields</h1> <h1 id="test">Fields</h1>

<p>first</p>
<p>last</p>
<p>email</p>

This script iterates over fieldsin the current record, retrieving their values. Then it adds the
values to a paragraph.

for(var i in record.fields){

results.after("<p>" + record.fields[i] + "</p>");

}

Selector Matched element Matched element after script execution

#test <h1 id="test">Fields</h1> <h1 id="test">Fields</h1>

<p>Peter</p>
<p>Parker</p>
<p>[e-mail]</p>

formatter

The formatter is a global object that allows you to format values in a script.

Page 51

The Text Script Wizard also allows you to format variable data; see "Using the Text Script

Note

The TextFormatter object is now deprecated and will eventually be removed.

Note

Loadhtml() iscached per batch run (based on the URL) in print/email.

Wizard" on page 161 and "Formatting variable data" on page 164.

Functions

l date()
l dateLong()
l dateMedium()
l dateShort()
l dateTime()
l dateTimeLong()
l dateTimeMedium

()

l dateTimeShort()
l timeLong()
l timeMedium()
l timeShort()

l lowerCase()
l upperCase()
l properCase()

loadhtml()

The date, dateTime and time functions allow you to format a date
and/or time. See "Date, date/time and time functions" on page 45.

The text formatting functions transform all characters to
lowercase (lowerCase) or uppercase (upperCase) or transforms
the first character of each word to uppercase and all other
characters to lowercase (properCase).

Global function thatreplaces the content (inner html) of each matched element in the result set,
alternatively load the data into a variable.The location should be an URL or a relative file path.

l loadhtml(location)
l loadhtml(location, selector)

Page 52

loadhtml(location)

Loads allHTML from the HTML file.

location

String containing a path that can be absolute or relative to the section/context. Use:
snippets/<snippet-name> to retrieve the content from a HTML fileresiding in the Snippets
folder on the Resources panel.

Examples

This script loads a local HTML snippet (from the Resources panel) directly into the matched
elements

results.loadhtml("snippets/snippet.html");

The following script loads a local HTML snippet (Resources panel) into a variable
The replaceWith()command is used to replace the element(s) matched by the script's selector
with the contents of the snippet.

var mysnippet = loadhtml('snippets/snippet.html');
results.replaceWith(mysnippet);

Same result as the previous script, but a different notation:

results.replaceWith(loadhtml('snippets/snippet.html'));

The following script loads a snippet into a variable and finds/replaces text in the variable before
inserting the content into the page. The second find command also adds formatting to the
replacing text.

var mysnippet = loadhtml('snippets/snippet.html');
mysnippet.find('@var1@').text('OL Connect 1');
mysnippet.find('@var2@').html('<i>OL Connect 2</i>').css('text­decoration','underline');
results.replaceWith(mysnippet);

This last script loads a snippet into a variable and retrieves an element from the snippet using
query().

var mysnippet = loadhtml('snippets/text-root-wrapped.html');
var subject = query("#subject", mysnippet).text();

Page 53

results.append("<p style='font-weight: bold;'>" + subject +
"</p>");

loadhtml(location, selector)

Retrieve specific content from the filename.

location

String; the location can be absolute or relative to the section/context. Use: snippets/<snippet­name> to retrievethe contentfrom a HTML fileresiding in snippets folder of the Resources
panel.

selector

String. The supplied selector should conform to CSS selector syntaxand allows you to
retrieve only the content of matching elements.

Examples

This script loads a specific element from the snippet.

var mysnippet = loadhtml('snippets/snippet­selectors.html','#item3');
results.replaceWith(mysnippet);

This script loads the children of the selected element.

var snippet = loadhtml('snippets/snippet.html','foobar').children
();
results.replaceWith(snippet);

Another example is given in the following how-to: Using a selector to load part of a snippet.

loadjson()

Creates a JSON object based on the text retrieved fromthe suppliedlocation. The function lets
you retrieve content from an JSON enabled server using a standard HTTP request. Popular
content management systems, like WordPress (requires JSON API plug-in) and Drupalprovide
a JSON service/API to retrieve content.

l loadjson(location)

Page 54

Note

Loadjson() is cached per batch run (based on the URL) in print/email.

This online JSON viewer is handy to debug JSON data: http://jsonviewer.stack.hu

loadjson(location)

Loads json data from a remote location.

location

String; the supplied location should be either a URL or a relative filepath.

Examples

This sample script retrieves JSON data from a snippet.

var localJSON = loadjson('snippets/jsonsnippet.html');
if(localJSON.post){

results.html("<h3>" + localJSON.post.title + "</h3><p>" +
localJSON.post.modified + "</p>");
}

This script retrieves a post from a WordPress site.

var wpPost = loadjson('http://192.168.101.58/2013/06/leave-the­third-dimension-behind-and-focus-on-real-printing­innovation/?json=1');
if(wpPost.post){

results.html("<h1>" + wpPost.post.title + "</h1>"

+ wpPost.post.content);

}

This script retrieves multiple posts from a WordPress site.

var numPosts = 3;
var wpPost = '';
var wpRecentPosts = loadjson('http://192.168.101.58/?json=get_
recent_posts&count=' + numPosts);
if(wpRecentPosts.posts){

for (var i = 0; i < numPosts ; i++) {

wpPost += "<p>" + wpRecentPosts.posts[i].title + "</p>";

}

Page 55

}
results.after(wpPost)

prepend()

Insert contentat the beginningof each element in the set of HTML elements that match the
selector of the script or of another query in the template (see "query()" on page 58).See also:
"append()" on page 36.

prepend(content)

Insert contentas the first element toeach element in the set of HTML elements that match the
selector of the script or of another query in the template (see "query()" on page 58).Append
creates a new result set.

content

HTML string, string or HTML string to insert after the matched elements. In case a plain text
string is provided, it is automatically wrapped in a <span> element to avoid orphan text nodes
to appear in the <body> element.

Examples

This script inserts a heading as the first element in an element that has the ID #box.

results.prepend("<h1>Personal information</h1>");

Selector Matched element Matched element after script execution

#box <div id="box">

<p>Peter Parker</p>
</div>

This script inserts a heading as the first element in an element that has the class name.

results.prepend("<b>Name: </b>");

Selector Matched element Matched element after script execution

<div id="box">

<h1>Personal information</h1>
<p>PeterParker</p>
</div>

.name <div> <div>

Page 56

<h1>Personal

<h1>Personal information</h1>

information</h1>

<p class="name">Peter

Parker</p>

</div>

This script inserts content in multiple <div> elements at the same time.

results.prepend("<h1>Personal information</h1>");

Selector Matched element Matched element after script execution

div <div id="box">

<p>Peter Parker</p>
</div>
<div id="box">
<p>Peter Parker</p>
</div>

<div id="box">
<h1>Personal information</h1>
<p>PeterParker</p>
</div>

<div id="box">
<h1>Personal information</h1>
<p>PeterParker</p>

<p class="name"><b>Name: </b>Peter

Parker</p>

</div>

</div>

This script prepends a snippet that contains the text "<h1>Personal information</h1>".

var a = loadhtml('snippets/snippet.html');
results.prepend(a);

Selector Matched element Matched element after script execution

div <div id="box">

<p>Peter Parker</p>
</div>

This script uses the function query() to find a box. Then it inserts a heading as the first element
in that box.

<div id="box">

<h1>Personal information</h1>
<p>PeterParker</p>
</div>

query("#box").prepend("<h1>Personal information</h1>");

Page 57

Matched element Matched element after script execution

<div id="box">

<p>Peter Parker</p>
</div>

<div id="box">

<h1>Personal information</h1>
<p>PeterParker</p>
</div>

This script uses the function query() to find a box, prepends a heading and sets the text color of
the entire box to red.

query("#box").prepend("<h1>Personal information</h1>").css
("color","red");

Matched element Matched element after script execution

<div id="box">

<p>Peter Parker</p>
</div>

<div id="box"style="color: red;">

<h1>Personal information</h1>
<p>Peter Parker</p>
</div>

Note: the way the functions prepend() and css() are used in this script is called 'chaining'.
Chaining is optional; the same could be achieved by storing the result of the query in a
variable:

var box = query("#box");
box.prepend("<p>Peter Parker</p>");
box.css("color","red");

query()

Creates a new result set containing the HTML elements that match the supplied CSS selector.
The context (optional) allows you to restrict the search to descendants of one or more context
elements.

l query(selector)
l query(selector, context)

Page 58

query(selector)

Creates a new result set containing the HTML elements in the template that match the supplied
CSS selector.

selector

A String containing a CSS selector. See http://www.w3schools.com/cssref/css_selectors.asp
for CSS selectors and combinations of CSS selectors.

query(selector, context)

Creates a new result set containing the HTML elements that match the supplied CSS selector.
The context (optional) allows you to restrict the search to descendants of one or more context
elements.

selector

A String containing a CSS selector. See http://www.w3schools.com/cssref/css_selectors.asp
for CSS selectors and combinations of CSS selectors.

context

A result set or an HTML string. If the passed context is not a result set of HTML string it will be
coerced to a String and interpreted as HTML.

Examples

Look for an element with a certain ID

This scripts applies a style rule to the queried elements.

query("#test1").css("color", "yellow");

Matched element Matched element after script execution

<p id="test1">foo</p> <p id="test1" style="color: yellow;">foo</p>

Look for an element in a snippet

The following script loads a snippet. Then it looks up an element in a snippet and sets its text.
Finally, it replaces the elements matched by the script's selector by the snippet.

var snippet = loadhtml('snippets/mysnippet.html');
query("#foo", snippet).text("bar");
results.replaceWith(snippet);

Page 59

CopyFile()

Examples

removeClass()

Removes the specified class from each element in this result set. Has no effect if the class is
not present.

removeClass(classname)

classname

String, space separated list of class names.

Examples

This script removes the class name "foo" from all elements in the results that have this class.

results.addClass("foo");

Selector Matched element Matched element after script execution

p <p class="foo">Hello world</p> <p>Hello world</p>

replaceWith()

Replaces each element in a set of HTML elements.

replaceWith(content)

Replaces each element in a set of HTML elements. Returns the result set.

content

A query result. This can be an HTML string or a result set.

Page 60

Examples

Replace elements with a snippet

The following script loads a snippet and then replaces the elements matched by the script's
selector with the snippet.

var snippet = loadhtml('snippets/mysnippet.html');
results.replaceWith(snippet);

Replace elements with a set of snippets

The following script loads snippets and adds their elements to a new, empty result set (using

query()). Then it replaces a placeholder in the template with the set of snippets.

var chapters = query();
for ( var i = 1; i <= 4; i++) {
chapters = chapters.add(loadhtml('snippets/Chapter' + i +
'.html'));
}
results.replaceWith(chapters);

Control Script API

When output is generated from a template, Control Scripts run before all other scripts. This topic
lists features that can only be used in Control Scripts and provides some sample scripts. See
"Control Scripts" on page 208 for more information about how to use this kind of scripts.

Objects available to pre-merge scripts

Channel

This is an enumeration for the output channels. The active output channel is registered in

merge.channel.

Value Description

EMAIL The merge request is for output to Email

PRINT The merge request is for output to Print

WEB The merge request is for output to Web

THUMBNAIL The merge request is for generating a template preview

Page 61

ContextType

This is an enumeration for the context types.

Value Description

HTML_EMAIL The context is the Email context

PRINT The context is the Print context

WEB The context is the Web context

Merge

The root level instance of the object merge is the entry point in Control Scripts for the objects
and references required to query and modify various aspects.

Field Type Description

context Context The context rendered by this merge pass.

channel Channel The channel for which this merge pass is requested.

section Section The section being merged. Only available from non-control

template scripts AND when the output channel is WEB
(merge.channel == Channel.WEB) where it defines the requested
page.

template Template Template containing the context. This field can be used to find out

which contexts are available in the template.

Context

Context is an object representing the respective context in the template. Which contexts are
available in the template can be queried using merge.template.contexts. The context being
merged can be queried using merge.context.

Field Type Description

Page 62

sections Array Array of sections inside this context defined in the template.

type ContextType The context type.

Template

Template is an object representing the template. Which contexts are available in the template
can be queried using merge.template.contexts. The context being merged can be queried
using merge.context.

Field Type Description

contexts Array Array of contexts available in the template.

Section

A section object relating to a section in the template. This type can be used to query and modify
the output behavior for when the related context/section is merged.

Field Type Description

enabled boolean Enables or disables this section for output. Note

that even if a section is disabled the part and
restartPageNumber fields are still effective to

define the parts division and page numbering over
multiple sections when applicable.

The default enabled state for sections (before any
control script runs) is as follows (to emulate the
behavior of previous versions):
For Web channel requests the requested web
section is enabled by default. It is possible to
redirect to another section by disabling the
requested section and enabling another section.
For Email channel requests on the Web context
only the default section is enabled by default. It is
possible to enable different or multiple sections, to
control which sections will be attached to the

Page 63

email.
For Email channel requests on the Print context
all Print sections are enabled by default. It is
possible to enable different or multiple sections to
control which sections will be attached to the
email.
For Print channel requests on the Print context all
sections are enabled by default.

name [READONLY]

String

part String Name for the part. This is used for channels that

restartPageNumber boolean Enables or disables a restart of the page

The name of the section as shown in the
resources view. Note that sections cannot have an
integer as name. The name should always
include alphanumeric characters. See "
Renaming a section" on page 213.

can output separate and/or named parts. The
Email output, for example, can attach 3 PDF's
generated from the Print context. Part is used to
specify where a new part starts and the title for the
part. When used for Email attachments, the part
title is used as the file name for the attachment.

numbering. When generating Print output this can
be used to let page numbering continue over
multiple sections.
The default value is false, meaning that each
section will start with page 1 (to emulate behavior
of previous versions).

BackgroundResource

This is an enumeration for the types of background resources for a Print section.

Field Description

DATAMAPPER_ A PDF file retrieved via the active Data Mapping Configuration. This

Page 64

PDF can be the PDF file that was used as input file, or another type of input

Note

From DataMapper input cannot be used in PrintShopMail

Connect. The DataMapper is included only in PlanetPress
Connect and PreS Connect.

file, converted to PDF.

NONE No PDF background.

RESOURCE_
PDF

A PDF file stored in the template or on the network. Note that it isn't
possible to use a remotely stored PDF file as a section's background.

MediaPositon

This is an enumeration for the position of background resources (background.position) for a
Print section.

Field Description

ABSOLUTE Places the PDF at a specific location on the page. Set the background's top

(background.top) and left (background.left) measured from the top
and left side of the section.

CENTERED Centers the PDF on the page, vertically and horizontally.

FIT_TO_

Stretches the PDF to fit the page size.

MEDIA

Pitfalls to avoid

When using merge.context or merge.section make sure to check for the appropriate
conditions.

l merge.section is only defined when when the output channel is Web. To make sure

that it is defined, use the following if statement: if (merge.channel ==
Channel.WEB && merge.context.type == ContextType.WEB) { ... }.

Page 65

l When using merge.context.sections keep in mind that for example 'Section X'

might only exist in your Print context, so using merge.context.sections
['Section X'] without enclosing it in the if statement if
(merge.context.type == ContextType.PRINT) {} will yield an error when

the script runs for other contexts. Instead of enclosing it in an if statement, you can use
the template object to access a specific context:
merge.template.contexts.PRINT.sections['Section X'] .

Sample scripts

Conditionally skipping or printing Print sections

var printSections = merge.template.contexts.PRINT.sections;
printSections['Section EN'].enabled = false;
printSections['Section FR'].enabled = false;

if(record.fields.Language === 'FR'){

printSections['Section FR'].enabled = true;

} else {

printSections['Section EN'].enabled = true;

}

Selecting different sections for Print output and Email PDF attachment

var printSections = merge.template.contexts.PRINT.sections;

if(merge.channel === Channel.EMAIL){

printSections['Section 1'].enabled = false;
printSections['Section 2'].enabled = true;

}

if(merge.channel === Channel.PRINT){

printSections['Section 1'].enabled = true;
printSections['Section 2'].enabled = false;

}

Setting the name of Email PDF attachments

var section = merge.template.contexts.PRINT.sections['Section 1'];
section.part = 'Invoice ' + record.fields['InvoiceNo'];

Controlling multiple Email attachments

The following script attaches the following sections to an email:

Page 66

l Print section 3 + 4 as attachment with continued page numbers

Note

For another example, see this how-to: Output sections conditionally.

l Print section 6 as separate attachment
l Web sections A and B as separate attachment

if (channel == Channel.EMAIL) { // only when generating Email
output
if (merge.context.type == ContextType.PRINT) {

merge.context.sections['Section 1'].enabled = false;
merge.context.sections['Section 2'].enabled = false;
merge.context.sections['Section 3'].enabled = true;
merge.context.sections['Section 3'].part = "PDFAttach1";
merge.context.sections['Section 4'].enabled = true;
merge.context.sections['Section 4'].restartPageNumber = false;
merge.context.sections['Section 5'].enabled = false;
merge.context.sections['Section 6'].enabled = true;
merge.context.sections['Section 6'].part = "PDFAttach2";

} else if (merge.context.type == ContextType.WEB) {

merge.context.sections['default Section'].enabled = false; //

disable whatever is the default section

merge.context.sections['Section A'].enabled = true;
merge.context.sections['Section A'].part = "WebPartA";
merge.context.sections['Section B'].enabled = true;

merge.context.sections['Section B'].part = "WebPartB";
}
}

Setting the background of a Print section

The following script sets the background for a section called 'Policy' to RESOURCE_PDF and
specifies a path for it, using a data value:

// Enable the section background and specify that the PDF should be
read
// from a resource file rather than using a PDF DataMapper
background
merge.template.contexts.PRINT.sections['Policy'].background.source
= BackgroundResource.RESOURCE_PDF;

Page 67

// Specify the path
var resourceUrl = 'images/policy-' + record.fields.policy + '.pdf';
merge.template.contexts.PRINT.sections['Policy'].background.url =
resourceUrl;

Positioning the background of a Print section

Using abolute positioning

var activeSection = merge.template.contexts.PRINT.sections['Section
1'];
activeSection.background.source = BackgroundResource.RESOURCE_PDF;
activeSection.background.position = MediaPosition.ABSOLUTE;
activeSection.background.left = "10mm";
activeSection.background.top = "10mm";
activeSection.background.url = "images/somepage.pdf";

Scaling to Media size

var activeSection = merge.template.contexts.PRINT.sections['Section
1'];
activeSection.background.source = BackgroundResource.RESOURCE_PDF;
activeSection.background.position = MediaPosition.FIT_TO_MEDIA;
activeSection.background.url = "images/somepage.pdf";

Basic Steps

With the Designer you can create templates for personalized letters and emails, and generate
output from them.

These are the basic steps for creating and developing a template:

1.

Create a template

Create a template, using one of the Template Wizards. See "Creating a template" on
page 243.

2.

Fill the template

Add text, images and other elements to the template and style them. See "Content
elements" on page 72 and "Styling and formatting" on page 217.

3.

Personalize the content

Personalize the content using variable data. See "Personalizing Content" on page 151.

Page 68

4.

Note

Steps 2 and 3 are not necessarily to be followed in this order. For example, as you add
elements to a template, you may start personalizing them right away, before adding other
elements to the template.

Generate output

Adjust the settings, test the template and generate output: letters and emails. See
Skin/Formats/CrossReferencePrintFormat("Generating outputWhen merged with a record
set, the templates made in the Designer can generate twotypes of output: Print, and
Email.Print outputPrint templates, also called Print sections, are part of the Print context.
They are meant to be printed to a printer or printer stream, or to a PDF file (see Generate
Print output). The Print context can also be added to Email output as a PDF attachment;
see Generating Email output. When generating output from the Print context, each of the
Print sections is added to the output document, one after the other in sequence, for each
record. To dynamically select a section for output, use a Control Script; see Control
Scripts.There is a number of settings in the Print context and Print sections that have an
impact on how the Print context is printed; see Print settings in the Print context and
sections.To split the Print output into several files, see Splitting printing into more than
one file.Email outputThe Email context outputs HTML email with embedded formatting to
an email client through the use of an email server. The HTML generated by this context is
meant to be compatible with as many clients and as many devices as possible.Although
the Email context can contain multiple Email templates, only one of them can be merged
with each record. Which one is used, depends on a setting; see Email output settings in
the Email context and sections.Email is sent in a single batch for the whole record set. To
test a template, you can send a test email first. Output, generated from an Email template,
can have the following attachments:The contents of the Print context, in the form of a
single PDF attachment. Other files, an image or a PDF leaflet for example.Attaching the
Print context is one of the options in the Send (Test) Email dialog; see Generating Email
output. To learn how to attach other files, see Email attachments." on page 1).

Features

The Designer is Connect's module to create templates for personalized customer
communications. These are some of the key features in the Designer:

"Contexts" on page 71. A context contains one or more designs for one output channel.

Page 69

"Content elements" on page 72. Elements make up the biggest part of the content of each
design.

"Email" on page 127. Email is one of the intended output channels. This topics helps you
design an email template.

Skin/Formats/CrossReferencePrintFormat("Generating outputWhen merged with a record set,
the templates made in the Designer can generate twotypes of output: Print, and Email.Print
outputPrint templates, also called Print sections, are part of the Print context. They are meant to
be printed to a printer or printer stream, or to a PDF file (see Generate Print output). The Print
context can also be added to Email output as a PDF attachment; see Generating Email output.
When generating output from the Print context, each of the Print sections is added to the output
document, one after the other in sequence, for each record. To dynamically select a section for
output, use a Control Script; see Control Scripts.There is a number of settings in the Print
context and Print sections that have an impact on how the Print context is printed; see Print
settings in the Print context and sections.To split the Print output into several files, see Splitting
printing into more than one file.Email outputThe Email context outputs HTML email with
embedded formatting to an email client through the use of an email server. The HTML
generated by this context is meant to be compatible with as many clients and as many devices
as possible.Although the Email context can contain multiple Email templates, only one of them
can be merged with each record. Which one is used, depends on a setting; see Email output
settings in the Email context and sections.Email is sent in a single batch for the whole record
set. To test a template, you can send a test email first. Output, generated from an Email
template, can have the following attachments:The contents of the Print context, in the form of a
single PDF attachment. Other files, an image or a PDF leaflet for example.Attaching the Print
context is one of the options in the Send (Test) Email dialog; see Generating Email output. To
learn how to attach other files, see Email attachments." on page 1). Learn the ins and outs of
generating output from each of the contexts.

"Personalizing Content" on page 151. Personalize your customer communications using
variable data.

"Print" on page 170. Print is one of the intended output channels. This topic helps you design
and fill sections in the Print context.

"Sections" on page 212. Sections in one context are designed for the same output channel.

"Snippets" on page 216. Snippets help share content between contexts, or insert content
conditionally.

Page 70

"Styling and formatting" on page 217. Make your Designer templates look pretty and give them

Tip

If an Email context is going to be part of the template, it is recommended to start with an
Email Template Wizard; see "Creating an Email template with a Wizard" on page 247.
After creating a template, contexts can be added to it, but that can not be done with a
wizard.

the same look and feel with style sheets.

"Templates" on page 243. Start creating, using and sharing templates.

Web. Web is one of the intended output channels. This topic helps you design a web page.

"Write your own scripts" on page 195. Scripting can take personalization much further. Learn
how to script via this topic.

Contexts

Contexts are parts of a template that are each used to generate a specific type of output: Email
or Print.

l The Print context outputs documents to either a physical printer a PDF file; see "Print

context" on page 172.

l The Email context outputs HTML email, composed of HTML code with embedded CSS.

See "Email context" on page 128.

When a new template is made, the Context appropriate to that new template is automatically
created, including one section. After a template has been created, the other two contexts can be
added to it; see "Adding a context" on the facing page.

Outputting and combining contexts

All three contexts can be present in any template and they can all be used to output documents;
see "Generating Email output" on page 148, "Generating Print output" on page 138 and
Generating Web output.

They can even be combined in output.

Page 71

If present in the same template, a Print context and a Web context can be attached to an Email

Warning

No backup files are maintained in the template. The only way to recover a deleted
section, is to click Undo on the Edit menu, until the deleted section is restored. After
closing and reopening the template it is no longer possible to restore the deleted context
this way.

context.

Outputting other combinations of contexts, and selecting sections based on a value in the data,
can be done via a Control Script; see "Control Scripts" on page 208.

Adding a context

To add a context, right-click the Contexts folder on the Resources pane and click New print
context, New email context or New web context. Only one context of each type can be

present in a template. Each context, however, can hold more than one section; see "Sections"
on page 212.

Deleting a context

To delete a context, right-click the context on the Resources pane and click Delete.

Content elements

Once you have created template, it can be filled with all kinds of elements, from text to barcodes
and from tables to fields on a web form. All types of elements are listed on this page; see below.

There are several ways to insert elements, see "Inserting an element" on page 75.

Each element can have an IDand a class, as well as a number of other properties, depending
on the element's type. When an element is selected, its properties can be changed; see
"Selecting an element" on page 76, "Attributes" on page 74 and "Styling and formatting an
element" on page 77.

Page 72

When you add elements, such as text, images or a table, to the content of a template, you are

Tip

Wrapping elements in a box (see "Boxes" on page 114) or in a semantic HTML
element makes it easier to target them in a script or a style sheet. Place the cursor
in the element or select multiple elements. Then, on the menu, click Insert > Wrap
in Box. You can now use the wrapper element as a script's or style's selector; see
"Using the Text Script Wizard" on page 161 and "Styling and formatting" on page

217.

actually constructing an HTML file. It is possible to edit the source of the HTML file directly in
the Designer; see "Editing HTML" on the facing page.

Element types

The following types of content can be added to the content of a template:

l "Images" on page 119 and "Dynamic Images" on page 169
l "Text and special characters" on page 126
l "Date" on page 116
l "Table" on page 123
l "Boxes" on page 114: Positioned Box, Inline Box, Div and Span

l "Hyperlink and mailto link" on page 118
l "Barcode" on page 77
l "Whitespace elements: using optional space at the end of the last page" on page 183

(Print context only)

l "Page numbers" on page 184 (Print context only)
l Article, Section, Header, Footer, Nav and Aside are HTML5 semantic elements; see

http://www.w3schools.com/html/html5_semantic_elements.asp

l Other HTML elements: Heading, Address and Pre
l "Snippets" on page 216: a Snippet is a small, ready-to-use piece of content in a file
l Business graphics

Most elements are suitable for use in all contexts. There are a few exceptions, however. Forms
and Form elements can be used on web pages only, whereas Whitespace elements and Page
numbers can only be used in a Print context. Positioned boxes are well suited for Print
sections, but are to be avoided in the Email context.

Page 73

Whether it is best to use a Table or Box to position text, images and other elements, depends
on the context in which they are used; see "How to position elements" on page 230 for more
information.

Editing HTML

When you add elements, such as text, images or a table, to the content of a template, you are
actually constructing an HTML file.

To see this, toggle to the Design tab in the workspace. Click anywhere in the content. Take a
look at the breadcrumbs at the top of the workspace. The breadcrumbs show the HTML tag of
the clicked element, as well as the HTML tags of other elements to which the clicked element
belongs. The clicked element is at the end of the line.

To edit the HTMLtext directly:

l In the workspace, toggle to the Source tab.

On this tab you can view and edit the content of the template in the form of plain text with HTML
tags (note the angle brackets: <>). You may add and edit the text and the HTML tags, classes,
ID’s and other attributes.

To learn more about HTML, see for example https://developer.mozilla.org/en-

US/docs/Web/Guide/HTML/Introduction and http://www.w3schools.com/html/default.asp.

Many video courses and hands-on courses about HTML (and CSS) are offered on the Internet
as well, some for free. Go, for example, to www.codeschool.com or www.codeacademy.com
and look for HTML (and CSS) courses.

Attributes

ID and class

Every element in the content of a template can have an ID and a class. ID's and classes are
particularly useful with regard to variable data (see "Personalizing Content" on page 151) and
styling (see "Styling templates with CSS files" on page 219).

You can specify an ID and/or class when you add the element to the content.

Page 74

To add an ID and/or class to an element that has already been added to a template, select the
element (see "Selecting an element" on the facing page) and type an ID and/or a class in the
respective fields on the Attributes pane at the top right.

Other attributes

Apart from the ID and class, elements can have a varying number of properties, or 'attributes' as
they're called in HTML (see "Editing HTML" on the previous page). Which properties an
element has, depends on the element itself. An image, for example, has at least four attributes:

src (the image's URL), alt (alternate text), width and height. These attributes are visible on the

Attributes pane when you click an image in the content.

For each type of element, a small selection of attributes is visible on the Attributes pane at the
top right.

Changing attributes via script

Many attributes can be changed via the user interface. Another way to change attributes is by
using a script.

Any of the Script Wizards can produce a script that changes an attribute of an HTML element.
Set the Options in the Script Wizard to Attribute, to output the script's results to the value of a
specific attribute. See "Using the Text Script Wizard" on page 161.

In code, you can change an element's attribute using the function attr(); see "Write your own
scripts" on page 195 and "API" on page 27.

Inserting an element

To insert an element in the content of a template:

1.

Click the respective toolbar button. Alternatively, click the element on the Insert menu.

2. Add an ID and/or a class. ID's and classes are particularly useful with regard to variable
data (see "Personalizing Content" on page 151) and styling (see "Styling templates with
CSS files" on page 219).

3.

Use the Location drop-down to select where to insert the element.

l

At cursor position: The element is inserted where the cursor is located in the
template.

Page 75

l

Tip

Click the Edges button on the toolbar to make borders of elements visible on the Design
tab. The borders will not be visible on the Preview tab.

Before element: The element is inserted before the current HTML element where
the cursor is located. For example if the cursor is within a paragraph, insertion
occurs before the <p> tag.*

l

After start tag: The element is inserted within the current HTML element, at the
beginning, just after the start tag.*

l

Before end tag: The element is inserted within the current HTML element, at the
end, just before the end tag.*

l

After element: The element is inserted after the current element where the cursor is
located. For example if the cursor is within a paragraph, insertion occurs after the
end tag of the paragraph (</p>).*

* If the current element is located inside another element, use the Elements drop-down to
select which element is used for the insertion location. The list displays every element in
the breadcrumbs, from the current selection point until the root of the body.

Selecting an element

When an element is selected, the Attributes pane shows the attributes of that element, and the
Styles pane, next to the Attributes pane, shows which styles are applied to it.

To select an element in the content, you can of course click on it, but this isn't always as easy
as it seems, especially when the element has elements inside it.

There are two more ways to select an element in the content:

l Use the Breadcrumbs at the top of the workspace.

Breadcrumbs show the HTML tag of the clicked element, as well as the HTML tags of
'parent elements': elements inside of which the clicked element is located. The clicked

Page 76

element is at the end of the line.

Elements with classes or IDs show these details next to them, for instance div
#contents > ol.salesitems > li. Click any of the elements in the Breadcrumbs
to select that element.
If an element is selected in the Breadcrumbs and the Backspace key is pressed, that
element is deleted.

l

Use the Outline pane. You can find this pane next to the Resources pane. It displays a
tree view of the elements in the file. Click an element in the tree view to select it.

Styling and formatting an element

Format elements directly

Images and other graphical elements can be resized by clicking on them and dragging the
resize handles. There are toolbar buttons to color, indent or style text. Other toolbar buttons can
left-align, right-align, or rotate graphical elements.

The toolbar buttons only represent a selection of the formatting options for each element. There
are no toolbar buttons to change an element's margins, or to add a border to it, for example. To
access all formatting properties of an element, you have to open the Formatting dialog. There
are two ways to do this:

l Right-click the element and select the type of element on the shortcut menu.
l Select the element (see "Selecting an element" on the previous page) and select the type

of element on the Format menu.

See "Styling and formatting" on page 217 for more information about the formatting options.

Format elements via Cascading Style Sheets (CSS)

It is recommended to use style sheets in your templates right from the start, even more so if your
communications are going to be output to different output channels, or if they consist out of
different sections (for example, a covering letter and a policy). With CSS you can give your
templates one look and feel. A style sheet can change the look of multiple elements, making it
unnecessary to format each and every element in the template, time and again, when the
company's layout preferences change, for example. See "Styling templates with CSS files" on
page 219.

Barcode

In PrintShop Mail Connect Designer, you can add a variety of barcodes to your template. The
supported Barcode types include 1d barcodes (the striped ones) and 2d barcodes (encoded

Page 77

horizontally and vertically).

Note

When generating Print output, you can add extra barcodes and OMR marks. The reason why you
would do this, is that at merge time more information is available about the actual output document.
The page count, for example, is not available at design time.

To add barcodes and OMR marks on the fly when generating Print output, select File > Print and
check the option Add additional content (see "Additional Text" on page 340) in the Print

Wizard. To have this done automatically, save this and other output options in an Output Creation
Preset: select File > Print presets > Output Creation Settings (see "Output Creation
Settings" on page 384).

Adding a Barcode

Before adding a Barcode, load data or at least a Data Model; see "Loading data" on page 153.
You will need the field names when adding the Barcode. Then, to add a Barcode to a section,
Master Page or snippet:

1.

Select Insert > Barcode on the menu or click the Barcode toolbar button

2. Choose the desired barcode type. The list is divided between 1d and 2d barcodes.

3.

An ID is required. You can change the given ID and, optionally, add a class.

4.

Use the Location drop-down to select where to insert the Barcode.

l

At cursor position inserts the Barcode where the cursor is located in the template.

l

Before element inserts it before the HTML element in which the cursor is currently
located. For example if the cursor is within a paragraph, the Barcode is inserted
before the <p> tag.*

l

After start tag inserts it within the current HTML element, at the beginning, just after
the start tag.*

l

Before end tag inserts it within the current HTML element, at the end, just before
the end tag.*

l

After element inserts it after the element in which the cursor is currently located. For
example if the cursor is within a paragraph, the Barcode is inserted after the end tag
of the paragraph (</p>).*

l

Absolute on body inserts the Barcode in an absolute-positioned box inside the
<body> of the HTML, but outside other elements.

Page 78

* If the current element is located inside another element, use the Elements drop-down to

Note

For a detailed description or for background information on a specific barcode,
please refer to the documentation provided by the individual barcode supplier. Note
that some barcode readers may require specific parameters as well.

select which element is used for the insertion location. The list displays every element in
the breadcrumbs, from the current selection point until the root of the body.

5.

Under Script, select the field that contains the barcode value, or select the fields that
together compose the barcode value. When you select more than one field, the script puts
the values of the selected fields in one string and passes that to the barcode generator.
The barcode type dictates the length and exact format of the required value.
For barcodes that require a Checksum, the Designer can calculate a Checksum if that
isn't provided by your data. Then script result should be the required value minus the
Checksum. Edit the barcode properties to include the calculated Checksum with the
barcode value, after adding the barcode to the template; see below.

6.

Click OK to close the dialog.

In the template the barcode shows up as a gray box. The barcode script is added to the Scripts
pane. To see the barcode script working, toggle to the Preview tab in the Workspace.

Changing a barcode

Barcode script

The barcode script determines which value is fed to the barcode generator. Double-click the
script on the Scripts pane to change which field(s) are added to the barcode value.

Barcode properties

A barcode is always added with the barcode type's default properties. To change those
properties, such as the scale and color, open the Barcode properties dialog: right-click the
barcode (on the Design tab in the Workspace) and select the respective barcode on the
shortcut menu.

Click the barcode type below for information about its properties.

l "Code 11, Code 93, Code 93 extended, Industrial 2 of 5, Interleaved 2 of 5, Matrix 2 of 5"

on page 100

Page 79

l "Code 39, Code 39 extended" on page 86

Tip

As of version 1.5 it will be possible to change the type of a barcode in the template as well, when
changing the properties of a barcode.

l "UPC-A, UPC-E, EAN-8, EAN-13" on page 112
l "OneCode, KIX Code, Royal Mail, Australia Post" on page 110
l "Code 128" on page 89
l "GS1-128" on page 94
l "Codabar" on page 83
l "MSI" on page 102
l "IMPB" on page 96
l "Postnet" on page 106
l "QR Code" on page 108
l "Data Matrix" on page 90
l "Royal Mail Mailmark" on page 111
l "PDF417" on page 105
l "Aztec Code" on the next page
l "MaxiCode" on page 101

OneCode, KIX Code, Royal Mail, Australia Post

OneCode, KIX Code, Royal Mail and Australia Post are some of the types of barcodes that can
be added to a template; see "Barcode" on page 77.

The barcode can be added either using the Barcode toolbar button or through selecting Insert
> Barcode on the menu; see " Adding a Barcode" on page 78.

Initially the barcode will have the barcode type's default properties. To change those properties,
such as the scale and color, open the Barcode properties dialog: right-click the barcode (on the
Design tab in the Workspace) and select the barcode type on the shortcut menu.

Barcode properties

This topic lists the properties of the barcode types OneCode, KIX Code, Royal Mail and
Australia Post. For the properties of other barcode types, see "Barcode properties" on the
previous page.

Height, width and spacing

The height, width and spacing of the barcode are all measured in pixels (38 dpi).

Page 80

l

Bar height: the height of the (shorter) bars

l

Extended bar height: the total height of the extended bars

l

Bar width: the width of the bars

l

Spacing: the distance between the bars

Scale

Defines if and how the rendered barcode is scaled in relation to the parent element:

l

None: The barcode is rendered based on the module width.

l

Fit to box: The barcode is stretched to fit the parent box in both width and height.

l

Proportionally: The barcode is stretched up to where it fits either the width or height of
the parent box, whichever requires the less stretching.

Color

The Color property allows you to choose a different Barcode color (instead of black) and
Background color (instead of white), by typing a hexadecimal color value (see for example

w3school's color picker).

Output format

Defines how the barcode is output on the page. There are two possible formats:

l

SVG: Vector format. This is smaller in size, but not compatible with Email output.

l

PNG: Binary rasterized format. This is slightly larger than SVG but will display properly in
Email output.

Aztec Code

Aztec is one of the types of barcodes that can be added to a template; see "Barcode" on page

77.

The barcode can be added either using the Barcode toolbar button or through selecting Insert
> Barcode on the menu; see " Adding a Barcode" on page 78.

Initially the barcode will have the barcode type's default properties. To change those properties,
such as the scale and color, open the Barcode properties dialog: right-click the barcode (on the
Design tab in the Workspace) and select the barcode type on the shortcut menu.

Page 81

Barcode properties

This topic lists the properties of the barcode type Aztec. For the properties of other barcode
types, see "Barcode properties" on page 79.

Module size

Enter the size of the square modules in pixels

Configuration type

Use the drop-down to select the format type used when creating the barcode: only full range
format, only compact formats, or any format.

Preferred configuration

Use the drop-down to select the preferred format for the barcode. Note that the barcode
generator may choose a different format if the data cannot be represented by the preferred
format.

Encoding

Use the drop-down to select the encoding type:

l

Normal can encode any character but is not very efficient for encoding binary values
(above 128)

l

Binary is to be used only if the data contains many bytes/characters above 128.

Error Correction Level

This option reserves a percentage of the symbol capacity for error correction. The
recommended percentage for this type of barcode is 23.

Rune

When set to a value between 0 and 255, an Aztec Rune corresponding to the selected value is
created. Set the Rune to -1 to disable this feature.

Scale

Defines if and how the rendered barcode is scaled in relation to the parent element:

l

None: The barcode is rendered based on the module width.

l

Fit to box: The barcode is stretched to fit the parent box in both width and height.

Page 82

l

Proportionally: The barcode is stretched up to where it fits either the width or height of
the parent box, whichever requires the less stretching.

Color

The Color property allows you to choose a different Barcode color (instead of black) and
Background color (instead of white), by typing a hexadecimal color value (see for example

w3school's color picker).

Output format

Defines how the barcode is output on the page. There are two possible formats:

l

SVG: Vector format. This is smaller in size, but not compatible with Email output.

l

PNG: Binary rasterized format. This is slightly larger than SVG but will display properly in
Email output.

Codabar

Codabar is one of the barcode types that can be added to a template.

The barcode can be added either using the Barcode toolbar button or through selecting Insert
> Barcode on the menu; see " Adding a Barcode" on page 78.

Initially the barcode will have the barcode type's default properties. To change those properties,
such as the scale and color, open the Barcode properties dialog: right-click the barcode (on the
Design tab in the Workspace) and select the barcode type on the shortcut menu.

Barcode properties

This topic lists the properties of the Codabar barcode. For the properties of other barcode types,
see "Barcode properties" on page 79.

Module width

Specifies the width of the narrow bars in centimeters. Changing this value to a higher value will
make the barcode bigger when Scale is set to None.

Start Char and Stop Char

Use the drop-down to select the start and stop character for the barcode, which defines the
encoding mode. Available characters are A, B, C.

Page 83

Scale

Defines if and how the rendered barcode is scaled in relation to the parent element:

l

None: The barcode is rendered based on the module width.

l

Fit to box: The barcode is stretched to fit the parent box in both width and height.

l

Proportionally: The barcode is stretched up to where it fits either the width or height of
the parent box, whichever requires the less stretching.

Add Checksum

When checked, PrintShop Mail Connect will calculate a Checksum character and add that to
the result of the Barcode script. If the value to be encoded is longer than 10 digits, a second
check character will be calculated.

Human Readable Message

When this option is checked, PrintShop Mail Connect shows a human readable text below or
above the barcode, as defined using the Text Position, using the specified font and font size.
The font size is given in points (pt).

Color

The Color property allows you to choose a different Barcode color (instead of black) and
Background color (instead of white), by typing a hexadecimal color value (see for example

w3school's color picker).

Output format

Defines how the barcode is output on the page. There are two possible formats:

l

SVG: Vector format. This is smaller in size, but not compatible with Email output.

l

PNG: Binary rasterized format. This is slightly larger than SVG but will display properly in
Email output.

Code 11, Code 93, Code 93 extended, Industrial 2 of 5, Interleaved 2 of 5, Matrix 2 of 5

Code 11, Code 93, Code 93 extended, Industrial 2 of 5, Interleaved 2 of 5, and Matrix 2 of 5 are
a few of the barcode types that can be added to a template.

The barcode can be added either using the Barcode toolbar button or through selecting Insert
> Barcode on the menu; see " Adding a Barcode" on page 78.

Page 84

Initially the barcode will have the barcode type's default properties. To change those properties,
such as the scale and color, open the Barcode properties dialog: right-click the barcode (on the
Design tab in the Workspace) and select the barcode type on the shortcut menu.

Barcode properties

This topic lists the properties of the following barcode types :

l Code 11
l Code 93
l Code 93 extended
l Industrial 2 of 5
l Interleaved 2 of 5
l Matrix 2 of 5

For the properties of other barcode types, see "Barcode properties" on page 79.

Module width

Specifies the width of the narrow bars in centimeters. Changing this value to a higher value will
make the barcode bigger when Scale is set to None.

Scale

Defines if and how the rendered barcode is scaled in relation to the parent element:

l

None: The barcode is rendered based on the module width.

l

Fit to box: The barcode is stretched to fit the parent box in both width and height.

l

Proportionally: The barcode is stretched up to where it fits either the width or height of
the parent box, whichever requires the less stretching.

Add Checksum

When checked, PrintShop Mail Connect will calculate a Checksum character and add that to
the result of the Barcode script. If the value to be encoded is longer than 10 digits, a second
check character will be calculated.

Human Readable Message

When this option is checked, PrintShop Mail Connect shows a human readable text below or
above the barcode, as defined using the Text Position, using the specified font and font size.
The font size is given in points (pt).

Page 85

Color

The Color property allows you to choose a different Barcode color (instead of black) and
Background color (instead of white), by typing a hexadecimal color value (see for example

w3school's color picker).

Output format

Defines how the barcode is output on the page. There are two possible formats:

l

SVG: Vector format. This is smaller in size, but not compatible with Email output.

l

PNG: Binary rasterized format. This is slightly larger than SVG but will display properly in
Email output.

Code 39, Code 39 extended

Code 39 and Code 39 extended are two of the barcode types that can be added to a template.

The barcode can be added either using the Barcode toolbar button or through selecting Insert
> Barcode on the menu; see " Adding a Barcode" on page 78.

Initially the barcode will have the barcode type's default properties. To change those properties,
such as the scale and color, open the Barcode properties dialog: right-click the barcode (on the
Design tab in the Workspace) and select the barcode type on the shortcut menu.

Barcode properties

This topic lists the properties of the barcode types Code 39 and Code 39 extended. For the
properties of other barcode types, see "Barcode properties" on page 79.

Module width

Specifies the width of the narrow bars in centimeters. Changing this value to a higher value will
make the barcode bigger when Scale is set to None.

Inter Character Gap

Two adjacent characters are separated by an inter-character gap. A value of 1 means that the
separator will have the same length as the width of the narrow bars (in centimeters).

Scale

Defines if and how the rendered barcode is scaled in relation to the parent element:

Page 86

l

None: The barcode is rendered based on the module width.

l

Fit to box: The barcode is stretched to fit the parent box in both width and height.

l

Proportionally: The barcode is stretched up to where it fits either the width or height of
the parent box, whichever requires the less stretching.

Add Checksum

When checked, PrintShop Mail Connect will calculate a Checksum character and add that to
the result of the Barcode script. If the value to be encoded is longer than 10 digits, a second
check character will be calculated.

Human Readable Message

When this option is checked, PrintShop Mail Connect shows a human readable text below or
above the barcode, as defined using the Text Position, using the specified font and font size.
The font size is given in points (pt).

Color

The Color property allows you to choose a different Barcode color (instead of black) and
Background color (instead of white), by typing a hexadecimal color value (see for example

w3school's color picker).

Output format

Defines how the barcode is output on the page. There are two possible formats:

l

SVG: Vector format. This is smaller in size, but not compatible with Email output.

l

PNG: Binary rasterized format. This is slightly larger than SVG but will display properly in
Email output.

Code 11, Code 93, Code 93 extended, Industrial 2 of 5, Interleaved 2 of 5, Matrix 2 of 5

Code 11, Code 93, Code 93 extended, Industrial 2 of 5, Interleaved 2 of 5, and Matrix 2 of 5 are
a few of the barcode types that can be added to a template.

The barcode can be added either using the Barcode toolbar button or through selecting Insert
> Barcode on the menu; see " Adding a Barcode" on page 78.

Initially the barcode will have the barcode type's default properties. To change those properties,
such as the scale and color, open the Barcode properties dialog: right-click the barcode (on the
Design tab in the Workspace) and select the barcode type on the shortcut menu.

Page 87

Barcode properties

This topic lists the properties of the following barcode types :

l Code 11
l Code 93
l Code 93 extended
l Industrial 2 of 5
l Interleaved 2 of 5
l Matrix 2 of 5

For the properties of other barcode types, see "Barcode properties" on page 79.

Module width

Specifies the width of the narrow bars in centimeters. Changing this value to a higher value will
make the barcode bigger when Scale is set to None.

Scale

Defines if and how the rendered barcode is scaled in relation to the parent element:

l

None: The barcode is rendered based on the module width.

l

Fit to box: The barcode is stretched to fit the parent box in both width and height.

l

Proportionally: The barcode is stretched up to where it fits either the width or height of
the parent box, whichever requires the less stretching.

Add Checksum

When checked, PrintShop Mail Connect will calculate a Checksum character and add that to
the result of the Barcode script. If the value to be encoded is longer than 10 digits, a second
check character will be calculated.

Human Readable Message

When this option is checked, PrintShop Mail Connect shows a human readable text below or
above the barcode, as defined using the Text Position, using the specified font and font size.
The font size is given in points (pt).

Color

The Color property allows you to choose a different Barcode color (instead of black) and
Background color (instead of white), by typing a hexadecimal color value (see for example

Page 88

w3school's color picker).

Output format

Defines how the barcode is output on the page. There are two possible formats:

l

SVG: Vector format. This is smaller in size, but not compatible with Email output.

l

PNG: Binary rasterized format. This is slightly larger than SVG but will display properly in
Email output.

Code 128

Code 128 is one of the types of barcodes that can be added to a template; see "Barcode" on
page 77.

The barcode can be added either using the Barcode toolbar button or through selecting Insert
> Barcode on the menu; see " Adding a Barcode" on page 78.

Initially the barcode will have the barcode type's default properties. To change those properties,
such as the scale and color, open the Barcode properties dialog: right-click the barcode (on the
Design tab in the Workspace) and select the barcode type on the shortcut menu.

Barcode properties

This topic lists the properties of the barcode type Code 128. For the properties of other barcode
types, see "Barcode properties" on page 79.

Module width

Specifies the width of the narrow bars in centimeters. Changing this value to a higher value will
make the barcode bigger when Scale is set to None.

Code set

Set of characters to be used:

l

A: ASCII characters 00 to 95 (0–9, A–Z and control codes), special characters, and FNC
1–4

l

B: ASCII characters 32 to 127 (0–9, A–Z, a–z), special characters, and FNC 1–4

l

C: 00–99 (encodes each two digits with one code) and FNC 1

Page 89

In Auto mode, the barcode generator will automatically select the correct encoding mode (set A,
B or C) according to the input data.

Scale

Defines if and how the rendered barcode is scaled in relation to the parent element:

l

None: The barcode is rendered based on the module width.

l

Fit to box: The barcode is stretched to fit the parent box in both width and height.

l

Proportionally: The barcode is stretched up to where it fits either the width or height of
the parent box, whichever requires the less stretching.

Add Checksum

When checked, PrintShop Mail Connect will calculate a Checksum character and add that to
the result of the Barcode script. If the value to be encoded is longer than 10 digits, a second
check character will be calculated.

Human Readable Message

When this option is checked, PrintShop Mail Connect shows a human readable text below or
above the barcode, as defined using the Text Position, using the specified font and font size.
The font size is given in points (pt).

Color

The Color property allows you to choose a different Barcode color (instead of black) and
Background color (instead of white), by typing a hexadecimal color value (see for example

w3school's color picker).

Output format

Defines how the barcode is output on the page. There are two possible formats:

l

SVG: Vector format. This is smaller in size, but not compatible with Email output.

l

PNG: Binary rasterized format. This is slightly larger than SVG but will display properly in
Email output.

Data Matrix

Data Matrix is one of the types of barcodes that can be added to a template; see "Barcode" on
page 77.

Page 90

The barcode can be added either using the Barcode toolbar button or through selecting Insert
> Barcode on the menu; see " Adding a Barcode" on page 78.

Initially the barcode will have the barcode type's default properties. To change those properties,
such as the scale and color, open the Barcode properties dialog: right-click the barcode (on the
Design tab in the Workspace) and select the barcode type on the shortcut menu.

Barcode properties

This topic lists the properties of the QR barcode. For the properties of other barcode types, see
"Barcode properties" on page 79.

Dots per pixel

Type the number of dots per pixel. To optimize barcode quality a Data Matrix symbol should not
be printed with dots smaller than 4 pixels.

Encoding

The data represented in the symbol can be compressed using of the following algorithms.

l

ASCII is used to encode data that mainly contains ascii characters (0-127)

l

C40 is used to encode data that mainly contains numbers and uppercase characters.

l

Text is used to encode data that mainly contains numbers and lowercase

l

Base256 is used to encode 8 bit values

l

Auto Detect automatically detects the data content and encodes using the most
appropriate method.

l

None does not use any encoding.

Preferred format

Use the drop-down to select the size of the Data Matrix.

Scale

Defines if and how the rendered barcode is scaled in relation to the parent element:

l

None: The barcode is rendered based on the module width.

l

Fit to box: The barcode is stretched to fit the parent box in both width and height.

l

Proportionally: The barcode is stretched up to where it fits either the width or height of
the parent box, whichever requires the less stretching.

Page 91

Color

The Color property allows you to choose a different Barcode color (instead of black) and
Background color (instead of white), by typing a hexadecimal color value (see for example

w3school's color picker).

Output format

Defines how the barcode is output on the page. There are two possible formats:

l

SVG: Vector format. This is smaller in size, but not compatible with Email output.

l

PNG: Binary rasterized format. This is slightly larger than SVG but will display properly in
Email output.

UPC-A, UPC-E, EAN-8, EAN-13

UPC-A, UPC-E, EAN-8 and EAN-13 are a few of the barcode types that can be added to a
template.

The barcode can be added either using the Barcode toolbar button or through selecting Insert
> Barcode on the menu; see " Adding a Barcode" on page 78.

Initially the barcode will have the barcode type's default properties. To change those properties,
such as the scale and color, open the Barcode properties dialog: right-click the barcode (on the
Design tab in the Workspace) and select the barcode type on the shortcut menu.

Barcode properties

This topic lists the properties of the barcode types UPC-A, UPC-E, EAN-8 and EAN-13. For the
properties of other barcode types, see "Barcode properties" on page 79.

Module width

Specifies the width of the narrow bars in centimeters. Changing this value to a higher value will
make the barcode bigger when Scale is set to None.

Show guardbars

Checking this option adds guardbars to the barcode. Guardbars are bars at the start, in the
middle and at the end that help the barcode scanner to scan the barcode correctly.

Scale

Defines if and how the rendered barcode is scaled in relation to the parent element:

Page 92

l

Note

When the chosen supplement type doesn't match the data, the supplement data will
be skipped and the additional barcode will not be rendered.

None: The barcode is rendered based on the module width.

l

Fit to box: The barcode is stretched to fit the parent box in both width and height.

l

Proportionally: The barcode is stretched up to where it fits either the width or height of
the parent box, whichever requires the less stretching.

Supplement

UPC-A, UPC-E, EAN-13, and EAN-8 may all include an additional barcode to the right of the
main barcode.

l

Type: The supplement type can be 2-digit (originally used to indicate the edition of a
magazine or periodical) or 5-digit (used to indicate the suggested retail price for books). In
case this option is set to None, and the data includes digits for the 2 or 5 supplement, the
supplement data will be skipped and the additional barcode will not be rendered.

l

Height Factor: This is the relative height of the supplement's bars compared to the
normal bars.

l

Space Before : Defines the space between the main symbol and the supplement, in cm.

Human Readable Message

When this option is checked, PrintShop Mail Connect shows a human readable text below or
above the barcode, as defined using the Text Position, using the specified font and font size.
The font size is given in points (pt).

Color

The Color property allows you to choose a different Barcode color (instead of black) and
Background color (instead of white), by typing a hexadecimal color value (see for example

w3school's color picker).

Output format

Defines how the barcode is output on the page. There are two possible formats:

Page 93

l

SVG: Vector format. This is smaller in size, but not compatible with Email output.

l

PNG: Binary rasterized format. This is slightly larger than SVG but will display properly in
Email output.

GS1-128

GS1-128 is one of the types of barcodes that can be added to a template; see "Barcode" on
page 77.

The barcode can be added either using the Barcode toolbar button or through selecting Insert
> Barcode on the menu; see " Adding a Barcode" on page 78.

Initially the barcode will have the barcode type's default properties. To change those properties,
such as the scale and color, open the Barcode properties dialog: right-click the barcode (on the
Design tab in the Workspace) and select the barcode type on the shortcut menu.

Barcode properties

This topic lists the properties of the barcode type GS1-128. For the properties of other barcode
types, see "Barcode properties" on page 79.

Module width

Specifies the width of the narrow bars in centimeters. Changing this value to a higher value will
make the barcode bigger when Scale is set to None.

Scale

Defines if and how the rendered barcode is scaled in relation to the parent element:

l

None: The barcode is rendered based on the module width.

l

Fit to box: The barcode is stretched to fit the parent box in both width and height.

l

Proportionally: The barcode is stretched up to where it fits either the width or height of
the parent box, whichever requires the less stretching.

Add Checksum

When checked, PrintShop Mail Connect will calculate a Checksum character and add that to
the result of the Barcode script. If the value to be encoded is longer than 10 digits, a second
check character will be calculated.

Page 94

Human Readable Message

When this option is checked, PrintShop Mail Connect shows a human readable text below or
above the barcode, as defined using the Text Position, using the specified font and font size.
The font size is given in points (pt).

Color

The Color property allows you to choose a different Barcode color (instead of black) and
Background color (instead of white), by typing a hexadecimal color value (see for example

w3school's color picker).

Output format

Defines how the barcode is output on the page. There are two possible formats:

l

SVG: Vector format. This is smaller in size, but not compatible with Email output.

l

PNG: Binary rasterized format. This is slightly larger than SVG but will display properly in
Email output.

OneCode, KIX Code, Royal Mail, Australia Post

OneCode, KIX Code, Royal Mail and Australia Post are some of the types of barcodes that can
be added to a template; see "Barcode" on page 77.

The barcode can be added either using the Barcode toolbar button or through selecting Insert
> Barcode on the menu; see " Adding a Barcode" on page 78.

Initially the barcode will have the barcode type's default properties. To change those properties,
such as the scale and color, open the Barcode properties dialog: right-click the barcode (on the
Design tab in the Workspace) and select the barcode type on the shortcut menu.

Barcode properties

This topic lists the properties of the barcode types OneCode, KIX Code, Royal Mail and
Australia Post. For the properties of other barcode types, see "Barcode properties" on page 79.

Height, width and spacing

The height, width and spacing of the barcode are all measured in pixels (38 dpi).

l

Bar height: the height of the (shorter) bars

l

Extended bar height: the total height of the extended bars

Page 95

l

Bar width: the width of the bars

l

Spacing: the distance between the bars

Scale

Defines if and how the rendered barcode is scaled in relation to the parent element:

l

None: The barcode is rendered based on the module width.

l

Fit to box: The barcode is stretched to fit the parent box in both width and height.

l

Proportionally: The barcode is stretched up to where it fits either the width or height of
the parent box, whichever requires the less stretching.

Color

The Color property allows you to choose a different Barcode color (instead of black) and
Background color (instead of white), by typing a hexadecimal color value (see for example

w3school's color picker).

Output format

Defines how the barcode is output on the page. There are two possible formats:

l

SVG: Vector format. This is smaller in size, but not compatible with Email output.

l

PNG: Binary rasterized format. This is slightly larger than SVG but will display properly in
Email output.

IMPB

IMPB is one of the barcode types that can be added to a template; see "Barcode" on page 77.

The barcode can be added either using the Barcode toolbar button or through selecting Insert
> Barcode on the menu; see " Adding a Barcode" on page 78.

Initially the barcode will have the barcode type's default properties. To change those properties,
such as the scale and color, open the Barcode properties dialog: right-click the barcode (on the
Design tab in the Workspace) and select the barcode type on the shortcut menu.

Barcode properties

This topic lists the properties of the barcode type IMPB. For the properties of other barcode
types, see "Barcode properties" on page 79.

Page 96

Color

The Color property allows you to choose a different Barcode color (instead of black) and
Background color (instead of white), by typing a hexadecimal color value (see for example

w3school's color picker).

Output format

Defines how the barcode is output on the page. There are two possible formats:

l

SVG: Vector format. This is smaller in size, but not compatible with Email output.

l

PNG: Binary rasterized format. This is slightly larger than SVG but will display properly in
Email output.

Code 11, Code 93, Code 93 extended, Industrial 2 of 5, Interleaved 2 of 5, Matrix 2 of 5

Code 11, Code 93, Code 93 extended, Industrial 2 of 5, Interleaved 2 of 5, and Matrix 2 of 5 are
a few of the barcode types that can be added to a template.

The barcode can be added either using the Barcode toolbar button or through selecting Insert
> Barcode on the menu; see " Adding a Barcode" on page 78.

Initially the barcode will have the barcode type's default properties. To change those properties,
such as the scale and color, open the Barcode properties dialog: right-click the barcode (on the
Design tab in the Workspace) and select the barcode type on the shortcut menu.

Barcode properties

This topic lists the properties of the following barcode types :

l Code 11
l Code 93
l Code 93 extended
l Industrial 2 of 5
l Interleaved 2 of 5
l Matrix 2 of 5

For the properties of other barcode types, see "Barcode properties" on page 79.

Module width

Specifies the width of the narrow bars in centimeters. Changing this value to a higher value will
make the barcode bigger when Scale is set to None.

Page 97

Scale

Defines if and how the rendered barcode is scaled in relation to the parent element:

l

None: The barcode is rendered based on the module width.

l

Fit to box: The barcode is stretched to fit the parent box in both width and height.

l

Proportionally: The barcode is stretched up to where it fits either the width or height of
the parent box, whichever requires the less stretching.

Add Checksum

When checked, PrintShop Mail Connect will calculate a Checksum character and add that to
the result of the Barcode script. If the value to be encoded is longer than 10 digits, a second
check character will be calculated.

Human Readable Message

When this option is checked, PrintShop Mail Connect shows a human readable text below or
above the barcode, as defined using the Text Position, using the specified font and font size.
The font size is given in points (pt).

Color

The Color property allows you to choose a different Barcode color (instead of black) and
Background color (instead of white), by typing a hexadecimal color value (see for example

w3school's color picker).

Output format

Defines how the barcode is output on the page. There are two possible formats:

l

SVG: Vector format. This is smaller in size, but not compatible with Email output.

l

PNG: Binary rasterized format. This is slightly larger than SVG but will display properly in
Email output.

Code 11, Code 93, Code 93 extended, Industrial 2 of 5, Interleaved 2 of 5, Matrix 2 of 5

Code 11, Code 93, Code 93 extended, Industrial 2 of 5, Interleaved 2 of 5, and Matrix 2 of 5 are
a few of the barcode types that can be added to a template.

The barcode can be added either using the Barcode toolbar button or through selecting Insert
> Barcode on the menu; see " Adding a Barcode" on page 78.

Page 98

Initially the barcode will have the barcode type's default properties. To change those properties,
such as the scale and color, open the Barcode properties dialog: right-click the barcode (on the
Design tab in the Workspace) and select the barcode type on the shortcut menu.

Barcode properties

This topic lists the properties of the following barcode types :

l Code 11
l Code 93
l Code 93 extended
l Industrial 2 of 5
l Interleaved 2 of 5
l Matrix 2 of 5

For the properties of other barcode types, see "Barcode properties" on page 79.

Module width

Specifies the width of the narrow bars in centimeters. Changing this value to a higher value will
make the barcode bigger when Scale is set to None.

Scale

Defines if and how the rendered barcode is scaled in relation to the parent element:

l

None: The barcode is rendered based on the module width.

l

Fit to box: The barcode is stretched to fit the parent box in both width and height.

l

Proportionally: The barcode is stretched up to where it fits either the width or height of
the parent box, whichever requires the less stretching.

Add Checksum

When checked, PrintShop Mail Connect will calculate a Checksum character and add that to
the result of the Barcode script. If the value to be encoded is longer than 10 digits, a second
check character will be calculated.

Human Readable Message

When this option is checked, PrintShop Mail Connect shows a human readable text below or
above the barcode, as defined using the Text Position, using the specified font and font size.
The font size is given in points (pt).

Page 99

Color

The Color property allows you to choose a different Barcode color (instead of black) and
Background color (instead of white), by typing a hexadecimal color value (see for example

w3school's color picker).

Output format

Defines how the barcode is output on the page. There are two possible formats:

l

SVG: Vector format. This is smaller in size, but not compatible with Email output.

l

PNG: Binary rasterized format. This is slightly larger than SVG but will display properly in
Email output.

Code 11, Code 93, Code 93 extended, Industrial 2 of 5, Interleaved 2 of 5, Matrix 2 of 5

Code 11, Code 93, Code 93 extended, Industrial 2 of 5, Interleaved 2 of 5, and Matrix 2 of 5 are
a few of the barcode types that can be added to a template.

The barcode can be added either using the Barcode toolbar button or through selecting Insert
> Barcode on the menu; see " Adding a Barcode" on page 78.

Initially the barcode will have the barcode type's default properties. To change those properties,
such as the scale and color, open the Barcode properties dialog: right-click the barcode (on the
Design tab in the Workspace) and select the barcode type on the shortcut menu.

Barcode properties

This topic lists the properties of the following barcode types :

l Code 11
l Code 93
l Code 93 extended
l Industrial 2 of 5
l Interleaved 2 of 5
l Matrix 2 of 5

For the properties of other barcode types, see "Barcode properties" on page 79.

Module width

Specifies the width of the narrow bars in centimeters. Changing this value to a higher value will
make the barcode bigger when Scale is set to None.

Page 100