Print Service plugin

Modified on Wed, 4 Sep at 3:07 PM

Contents

The plugin Print Service is available separately and lets you create a PDF document from a form that is optimized for printing. This plugin is subject to additional charge.

Technical details

To use the Print Service plugin, it is necessary to install Node.js and the Print server. This can be installed on the same server as the FORMCYCLE master server.

Print Server installation instructions

Compatibility of Print Service plugin and Print Server

In principle, various versions of the Print Service plugin are compatible with practically all Print server versions. However, special features of the plugin are only supported with newer Print server versions.

We use semantic versioning for the version numbers of the Print server so that compatibility can be determined from the first two digits of the version number. A Print server with version 2.0.0 is therefore identical to a Print server with version 2.0.4 in regard to features and compatibility.

Plugin setup

Print Service plugin Installation

In order for the plugin to be available in formcycle as an action in the workflow, it must be deployed in the System Plugin section of the management interface. Instructions for installing plugins can be found here.

If the old version of the print service plugin (phantom plugin) was already installed, the following procedure is recommended for installation:

Disable the phantom plugin
Delete the phantom plugin
Upload new print service plugin
Proceed with the configuration

Plugin configuration

After the plugin has been installed, the service URL must be adjusted. This is defined in the plugin via the mandatory parameter pdf.print.services.url. If the installation was done on the same server as FORMCYCLE, then specify localhost as the domain. If no changes have been made to the port, the setting 8090 is retained.

For example: http://localhost:8089/pdf

This completes the setup of the print service plugin and it is available as an action in the workflow processing.

Log files for the plugin

Under Windows, the log files are stored in the daemon folder. If the installation directory has not been changed during installation, the files are stored under C:\Program Files\print_server_fc\daemon. In case of an error, the files formcycleprintserver.out.log and formcycleprintserver.err.log are relevant.

Under Linux, the log file is created directly in the print server directory, e.g. /home/USERNAME/print_server/printserver.log.

Usage and options

To use this plugin, go to the workflow processing configuration, click on new action and select this plugin. The following options are used to configure the plugin action:

File name: File name of the created PDF document.
Print mode: Input elements as text: Input elements are converted into plain text fields and the form is adapted to the width of the page.
Print mode: By default, are form fields such as input fields and select fields are converted to plain text. If you choose to disable this conversion, no changes are made to the form and it is printed so that it looks as closely as it does in a web browser as possible.
Pages to print: Names of the pages to print, separated by commas. When empty, prints all pages. For example: p1,p3,p5 only prints pages that are named either "p1", "p3", pr "p5".
Zoom factor: Scale factor for the form. Use this to magnify or scale down very large or very small forms.
Blank form: (requires at least print plugin version 4.2.0 and print service version 1.4.0) Can be used to create PDF documents that can be printed out and filled out manually with a pen. When enabled, all form field values are cleared and all hidden fields are shown. In addition, the maximum number of element repetitions are created.
User groups: A virtual user is created when opening the form with Selenium. Select the user groups here to which this virtual user should belong to. Form elements can be configured to be displayed or editable only for certain user groups.
URL parameter: Additional URL parameters added to the URL used when opening the form with Selenium. You can use URL parameters to prefill form fields or access them from within JavaScript.

CSS adjustments

General CSS adjustments can be done via a corresponding media query:

@media print {
   /* general CSS for printing */
}

Please note this CSS is applied in other printing contexts as well, e.g. when the user prints the form via the browser directly. There are a few special CSS classes available that are set only when the print service is used. These classes are always added to the form.xm-form element.(requires at least print plugin version 4.2.0 and print server plugin 1.4.0).

xm-print: This CSS class is always set.
xm-print--mode-plain: Added when print mode is set to Preserve form fields.
xm-print--mode-dynamic: Added when print mode is set to Convert form fields to text.
xm-print--style-filled: Added when the option blank form is disabled.
xm-print--style-blank: Added when the option blank form is enabled.

Input elements

To optimize the form for printing, form elements of type input field, text area und select (Drop-Down) may be converted to plain text fields, if the print mode is set to Input elements as text.

Additionally, the CSS classes print and XSpan are added to the converted input element that can be used for styling them. For example, in order to change the font size, you can use the following CSS:

.print.XSpan {
  font-size: 18pt;
  font-family: serif;
}

To overwrite some properties of the default CSS shipped with FORMCYCLE, use more specific selectors such as:

.xm-form .xm-content div.print.XSpan {
  font-size: 18pt;
  font-family: serif;
}

Most properties do not require this, however.

Enforce page break

To create a defined page break, the page-break attributes must be set via CSS. The corresponding container or element has to be selected via the xn attribute. Please note that the CSS property display must be set to block, otherwise no line break will be created. In this example, a line break should be created before the container div1.

[xn=div2] {
  display: block !important;
  page-break-before: always;
}

Avoid page break

The default setting for printing is that a page break is inserted after each page of the form:

@media print {
    .CXPage:not(:first-child ), .page-break {
        display: block !important;
        page-break-before: always;
    }
}

In order to avoid breaks, the following rule needs to be defined in the CSS tab of the form:

@media print {
    .CXPage:not(:first-child ) {
        page-break-before: avoid;
    }
}

Usage of other fonts

Technical requirements

In order for fonts to be used and embedded in the created PDF documents, it is generally necessary for them to be installed on the server running the Print-Server.

Inclusion via CSS

To include a font installed on the server for printing, it must be explicitly defined with a @media print query and set for use by the appropriate form elements. In the simplest case, this can look like the following example:

@media print {
    @font-face {
        font-family: 'DejaVu Sans';
        src: local('DejaVu Sans');
    }
    .xm-form.modern *, .modern .XPage * {
        font-family: "DejaVu Sans";
    }
}

Here it is especially important that the identifier entered at local() corresponds to the name of the font.

Legal notice

Fonts sometimes have very tightly defined license terms and are priced differently depending on their intended use. It should be noted that fonts for creating PDFs must be embedded in them, which for many commercial fonts requires a different license than for delivery via a web server for the purpose of displaying a web page in a web browser.

In fonts of type TrueType and OpenType information about the embeddability of the font can be stored directly. Depending on what is configured there, a font may not be embeddable and will instead be rendered by the Print-Service-Plugin only as a vector graphic in the created PDF documents.

JavaScript adjustments

Sometimes you may have to execute custom JavaScript code before the form is printed. For this, you can use the function $.xutil.onPrint. Its signature is as follows:

function onPrint(callback: () => Promise | void): void

This function lets you register one or more callbacks that are run before the form is printed. When a callback returns a promise, the print server waits until the promise fulfills before proceeding with the printing. In case the promise gets rejected, the error is logged, but the print is not aborted. Please note that you must register the callback before the form is printed, e.g. within a JQuery document-ready-handler ($(callback)).

Note: The print will be cancelled when the timeout specified in the action is reached.

For example, to run an AJAX request and wait for it to finish before the form is printed:

  $.xutil.onPrint(async () => {
    const response = await fetch("http://some-url.de");
    // do something with response
  });

  $.xutil.onPrint(function() {
    return new Promise(function(resolve, reject) {
      $.ajax("http://some-url.de", {
        success: function(data, textStatus, jqXHR) {
          // Do something with the response data
          resolve(undefined);
        },
        error: function(jqXHR, textStatus, errorThrown) {
          reject("HTTP request error: " + textStatus + " - " + errorThrown);
        },
      });
    });
  });

Troubleshooting

Information about error handling you will find here.

Changelog

Plugin

5.0.0

Requires at least version 8 of formcycle. Adaptations for version 8 of formcycle

4.4.4

Change: Plugin is correctly recognised again by formcycle version 8 and can be updated.

4.4.2

Change: Links to attachments are now deactivated in all print modes.

4.4.1

Change: Links for upload elements are no longer clickable. These have never worked because they require an active session ID.

4.4.0

feature: It is now possible to specify which pages are to be printed in the action.

4.3.0

feature: New option to retry printing in case of a failure

4.2.3

Fix: Special characters in combobox select options are now displayed correctly in the printed PDF document

4.2.2

Fix: When a textarea is set to adjust its height automatically to its content, the height is now recalculated once before the form is printed.

4.2.1

Fix: Show correct version of the print server when performing a check

4.2.0

feature: New option blank form
feature: Add special CSS classes to the form.xm-form such as xm-print
change: When an element is marked as hidden during print in the form designer (advanced -> Word and PDF export options), the element is now hidden when the print service is used as well. This feature requires at least FORMCYCLE version 7.0.14.
change: Applicable only when print mode is set to dynamic: When an input field did not have a value, its placeholders was shown instead. This was changed so that no value is shown when the input field does not have a value.
change: Applicable only when print mode is set to dynamic: When a select field displayed as a dropdown menu did not have a value, the text Please select was shown instead. This was changed so that no text is shown anymore when the select field does not have a value.

4.1.2

Added note regarding $.xutil.onPrint to the plugin UI.

4.1.1

Requires at least FORMCYCLE 7.0.4.
change: Note regarding required field is not shown anymore.
fix: Show the date format immediately

4.1.0

Added a new option for selecting the workflow state used during printing. When no state is selected, the current state of the form record is used as in previous version.
Configured user groups are saved correctly.

4.0.2

feature: Added a new timeout option that defaults to 30 seconds. When the print service cannot be reached, the workflow may never complete otherwise.

4.0.1

fix: The PDF document that was created was not attached to the form record (only for the new workflow action).

4.0.0

Adjustments for FORMCYCLE version 7.

Server

2.0.4

Update puppeteer at latest / Chrome 118.0.5993.70

2.0.3

Update puppeteer to 21.2.0 / Chrome 116.0.5845.96
Use server time for log entries, instead of GMT+0.

2.0.2

Disable new headless mode for Chrome again for the time being.

2.0.1

Also bind to IPv6 addresses by default.

2.0.0

Update Chromium browser used to print forms. Requires nodeJS 14+.

1.8.0

Browser tabs were not closed properly, resulting in unbounded RAM usage.
Delete Chrome profile directory on exit

1.7.0

Switch to media type print before printing and wait until no network traffic is ongoing anymore before printing. This helps to show e.g. background graphics from @media print rules.

1.6.1

Fix compatibility with Windows service installation script

1.6.0

Update puppeteer to latest version, which uses Chromium 108.0.5351.0
Add CLI flag --disableCache=true to disable the browser cache
Add CLI flag --isolatedBrowser=true to use a new browser instance for each request.
Fix Debian install script, install libgbm1.

1.5.1

Update node-windows dependency

1.5.0

Update to Chromium 105.0.5173.0
Requires at least Node.JS version 14 or higher

1.4.1

Fix windows service install / uninstall script (install-windows-service.js and uninstall-windows-service.js)

1.4.0

When an error occurs while printing, that error is returned as part of the HTTP response
The print server can now be used for printing arbitrary pages / URLs. JavaScript and CSS that must be run in the context of the page to print can be passed as part of the HTTP request.
The /pdf endpoint without parameters returns a quick summary of the server status