Wiki source code of Print-Service-Plugin

Hide last authors

version	line-number	content
28.7	1	[[Plugin-Download>>url:https://customer.formcycle.eu/index.php/apps/files/?dir=/FORMCYCLE%20-%20Plugins%20Customer/fc-plugin-print-service&fileid=8194\|\|rel="noopener noreferrer" target="_blank"]] (requires login)
1.1	2
4.3	3	{{info}}
28.7	4	{{formcycle/}} Version 7 requires the //Print-Service// plugin version to be 4.0.0 or higher.
4.3	5	{{/info}}
	6
1.1	7	{{content/}}
	8
28.7	9	The plugin //Print Services// 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.
1.1	10
28.7	11	== Technical details ==
1.1	12
28.7	13	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.
1.1	14
28.7	15	== Installation Print Server on Windows ==
1.1	16
28.7	17	The installation of the required //Print Server// requires different procedures depending on the operating system.
1.1	18
28.7	19	=== Installation of Node.js ===
4.1	20
28.7	21	: 1. Download the LTS version from https://nodejs.org/
	22	: 2. Run the MSI file
	23	: 3. Run the wizard steps, leaving default settings as they are
4.1	24
28.7	25	=== Installation steps for the Print Server ===
4.1	26
28.7	27	: 4. Download the Print Server installation files from the Customer Cloud [[here>>https://customer.formcycle.eu/index.php/apps/files/?dir=/FORMCYCLE%20-%20Plugins%20Customer/fc-plugin-print-service/Print%20Server&fileid=18856]].
	28	: 5. unzip the ZIP file "print_server_fc.zip" and move the content to the folder print_server_fc under {{code language="none"}}C:\Programs\{{/code}}.
4.1	29
28.7	30	To install, open the command line (cmd) with administrative privileges and execute the following commands:
	31
4.1	32	{{code language="none"}}
28.7	33	cd C:\Programs\print_server_fc
4.1	34	npm install
	35	npm install -g node-windows
	36	npm link node-windows
	37	node install-windows-service.js
	38	{{/code}}
	39
28.7	40	There now exists a new service {{code language="none"}}FORMCYCLE Print Server{{/code}}. Please check if this is also started before you run a [[test>>\|\|anchor="HTest"]]. The script {{code language="none"}}install-windows-service.js{{/code}} contains default variables for installing the print service.
4.1	41
28.7	42	* The service is installed on port 8090 by default. To change this, you need to adjust the {{code language="none"}}--port=8090{{/code}} parameter in the {{code language="none"}}install-windows-service.js{{/code}} file.
	43	* Logging is enabled by default. To change this set the parameter {{code language="none"}}--verbose=true{{/code}} to {{code language="none"}}--verbose=false{{/code}}.
4.1	44
28.7	45	After the installation, a folder named {{code language="none"}}deamon{{/code}} is created for the log files.
4.1	46
28.7	47	=== Uninstall ===
4.1	48
	49	Für die Deinstallation des Print Servers, öffnen Sie eine Kommandozeile (cmd) mit administrativen Berechtigungen und führen Sie folgende Befehle aus.
	50
	51	{{code language="none"}}
28.7	52	cd C:\Programs\print_server_fc
4.1	53	node uninstall-windows-service.js
	54	{{/code}}
	55
28.7	56	== Installing Print Server under Linux ==
6.1	57
28.3	58	{{info}}
28.7	59	Contrary to earlier versions, you need to copy ALL files from the ZIP file with the print server.
28.3	60	{{/info}}
	61
28.7	62	=== Installation steps for installing Node.js and the Print Server ===
6.1	63
28.7	64	To install, open the console and run the following commands:
6.1	65
4.1	66	{{code language="none"}}
28.7	67	# Loading the script (varies depending on the operating system)
4.1	68
28.7	69	# Debian 10 - If you are logged in as root:
4.1	70	wget "https://customer.formcycle.eu/index.php/s/0GBtp1HtQHJMzQx/download?path=/&files=install_printserver_debian10.sh" -O install_print_server.sh
	71
28.7	72	# Debian 10 - or if you are logged in as a normal user with sudo rights:
4.1	73	wget "https://customer.formcycle.eu/index.php/s/0GBtp1HtQHJMzQx/download?path=/&files=install_printserver_debian10_sudo.sh" -O install_print_server.sh
	74
28.7	75	# Ubuntu 16 - If you are logged in as root:
4.1	76	wget "https://customer.formcycle.eu/index.php/s/0GBtp1HtQHJMzQx/download?path=/&files=install_printserver_ubuntu16.sh" -O install_print_server.sh
	77
	78
28.7	79	# Make file executable
4.1	80	chmod 750 install_print_server.sh
	81
28.7	82
	83	# Start installation
4.1	84	./install_print_server.sh
	85
28.7	86
	87	# Run Print Server
4.1	88	systemctl start printserver
	89	{{/code}}
	90
28.7	91	In the first lines of the script - via the variables {{code language="none"}}PRINTSERVER_USER{{/code}} and {{code language="none"}}PRINTSERVER_USER_PWD{{/code}} - the user name/password to be created can be adjusted.
	92	The verbose parameter can be used to enable/disable the log output. The scripts for the service should be located at {{code language="none"}}/home/formcycle/print_server{{/code}}. In the start script the verbose parameter can be adjusted.
4.1	93
28.7	94	Translated with www.DeepL.com/Translator (free version)
4.1	95
28.7	96	=== Uninstall ===
4.1	97
28.7	98	To uninstall the Print Server, open a command line (cmd) with administrative privileges and execute the following commands:
	99
4.1	100	{{code language="none"}}
	101	/home/formcycle/deinstall_printserver.sh
	102	{{/code}}
	103
3.1	104	{{info}}
28.7	105	Caution:
	106	During the installation, depending on the existing system, some Linux packages such as nodejs were also installed. However, it is not possible to uninstall the packages automatically. Delete the automatically installed packages only if you are 100% sure that they are no longer needed!
3.1	107	{{/info}}
1.1	108
28.7	109	== Using IPv6 ==
6.1	110
28.7	111	Starting with version 2.0.1, the server binds to both IPv4 and IPv6 addresses by default, using the dual stack feature supported by most operating systems. Should that fail, the print server binds only to IPv4 addresses (0.0.0.0).
6.1	112
28.7	113	If required, you can also set a different bind address via the command line parameter "--bindAddress".
6.1	114
23.1	115	== Test ==
1.1	116
28.7	117	To check if the installation was successful, the service can be called on the local server for a test (in that case it should be printed the formcycle.de website):
4.1	118
23.1	119	{{code language="none"}}
	120	http://localhost:8090/pdf?orientation=landscape&format=A4&wait=false&marginTop=0mm&formURL=http://www.formcycle.de
	121	{{/code}}
4.1	122
28.7	123	== Plugin setup ==
23.1	124
28.7	125	=== Print-Service Plugin Installation ===
4.1	126
28.7	127	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>>doc:Formcycle.UserInterface.Client.Plugins.WebHome]].
4.1	128
28.7	129	If the old version of the print service plugin (phantom plugin) was already installed, the following procedure is recommended for installation:
5.1	130
28.7	131	* Disable the phantom plugin
	132	* Delete the phantom plugin
	133	* Upload new print service plugin
	134	* Proceed with the configuration
4.1	135
28.7	136	=== Plugin configuration ===
4.1	137
28.7	138	After the plugin has been installed, the service URL must be adjusted. This is defined in the plugin via the mandatory parameter {{code language="none"}}pdf.print.services.url{{/code}}.
4.1	139
28.7	140	If the installation was done on the same server as {{formcycle/}}, then specify {{code language="none"}}localhost{{/code}} as the domain. If no changes have been made to the port, the setting {{code language="none"}}8090{{/code}} is retained.
4.1	141
28.7	142	For example: {{code language="none"}}http://localhost:8089/pdf{{/code}}
4.1	143
28.7	144	This completes the setup of the print service plugin and it is available as an action in the [[workflow processing>>doc:Formcycle.Designer.Workflow.WebHome]].
4.1	145
28.7	146	== Troubleshooting ==
7.1	147
28.7	148	=== Command npm not found ===
7.1	149
28.7	150	Under Windows it is possible that after the NodeJS installation the environment variables are not set correctly and so npm install cannot be executed. This was also the case if the default path under C:/Programs was not used during the NodeJS installation. So check in the path if these are existing. The following must be done for this:
7.1	151
28.7	152	* Call up the environment variables via Control Panel > System > Advanced System Settings > Environment Variables button.
	153	* In Path you should find the following entries: {{info}}C:\Users\{username}\AppData\Roaming\npm;C:\Program Files\nodejs{{/info}}
	154	* Confirm everything with Ok. The console then be opened again with admin rights.
4.1	155
28.7	156	=== Command npm install leads to timeout ===
4.1	157
28.7	158	If the npm install command does not work due to a proxy, then the general proxy setting is not sufficient. Therefore, the following must be executed via console:
	159
4.1	160	{{code language="none"}}
	161	npm config set proxy http://proxy.domain:port
	162	npm config set https-proxy https://proxy.domain:port
	163	{{/code}}
	164
28.7	165	If user data is required:
4.1	166
	167	{{code language="none"}}
	168	npm config set proxy http://user:pass@proxy.domain:port
	169	npm config set https-proxy https://user:pass@proxy.domain:port
	170	{{/code}}
	171
28.7	172	More information can also be found here: http://www.fladi.de/2014/02/06/howto-npm-hinter-einem-proxy-verwenden/
4.1	173
28.7	174	=== Printing does not work ===
4.1	175
28.7	176	If printing via {{formcycle/}} is not possible, the cause could be that the print service is not reachable. This can be solved by the loopback URL. Under System > General > Loopback URL, loopback base URL: {{code language="none"}}http://localhost:<port>/formcycle{{/code}}
4.1	177
28.7	178	=== PDF is printed, but the message 404 appears ===
4.1	179
28.7	180	In this case the print service works correctly because a PDF is already created. It must be checked whether the loopback URL is entered correctly so that the URL to the print service is resolved correctly.
4.1	181
28.7	182	=== Downloading Chromium fails ===
4.1	183
28.7	184	The following error message appears on the console after running "npm install":
5.1	185	{{code language="none"}}Error: unable to verify the first certificate{{/code}}
4.1	186
28.7	187	The described steps are only a workaround and the environment variables should be set back to the default values after the successful installation!
4.1	188
	189	{{code language="none"}}
28.7	190	PS C:\test> $env:NODE_TLS_REJECT_UNAUTHORIZED = 0
	191	PS C:\test> npm set strict-ssl false
4.1	192	{{/code}}
	193
28.7	194	== Usage and options ==
4.1	195
28.7	196	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:
1.1	197
28.7	198	; File name
	199	: File name of the created PDF document.
	200	; Print mode
	201	: Input elements as text: Input elements are converted into plain text fields and the form is adapted to the width of the page.
	202	; Print mode
	203	: 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.
	204	; Zoom factor
	205	: Scale factor for the form. Use this to magnify or scale down very large or very small forms.
	206	; Blank form
	207	: (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.
	208	; User groups
	209	: 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.
	210	; URL parameter
	211	: Additional URL parameters added to the URL used when opening the form with Selenium. You can use URL parameters to [[prefill form fields>>Formcycle.Designer.Form.URLParameter]] or access them from within JavaScript.
13.1	212
28.7	213	== CSS adjustments ==
13.1	214
28.7	215	General CSS adjustments can be done via a corresponding media query:
13.1	216
16.2	217	{{code language="css"}}
	218	@media print {
	219	/* general CSS for printing */
	220	}
	221	{{/code}}
	222
28.7	223	Please note this CSS is applied in other printing contexts as well, e.g. when the user prints the form via the browser directly.
16.2	224
28.7	225	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).
16.2	226
	227	; xm-print
28.7	228	: This CSS class is always set.
16.7	229	; xm-print~-~-mode-plain
28.7	230	: Added when print mode is set to //Preserve form fields//.
16.7	231	; xm-print~-~-mode-dynamic
28.7	232	: Added when print mode is set to //Convert form fields to text//.
16.7	233	; xm-print~-~-style-filled
28.7	234	: Added when the option //blank form// is disabled.
16.7	235	; xm-print~-~-style-blank
28.7	236	: Added when the option //blank form// is enabled.
16.2	237
28.7	238	=== Input elements ===
1.1	239
28.7	240	To optimize the form for printing, form elements of type [[input field>>Formcycle.Designer.Form.FormElements.Input]], [[text area>>Formcycle.Designer.Form.FormElements.Textarea]] und [[select>>Formcycle.Designer.Form.FormElements.Selection]] (Drop-Down) may be converted to plain text fields, if the print mode is set to Input elements as text.
1.1	241
28.7	242	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:
	243
1.1	244	{{code language="css"}}
	245	.print.XSpan {
28.7	246	font-size: 18pt;
	247	font-family: serif;
1.1	248	}
	249	{{/code}}
	250
28.7	251	To overwrite some properties of the default CSS shipped with {{formcycle/}}, use more specific selectors such as:
1.1	252
	253	{{code language="css"}}
3.1	254	.xm-form .xm-content div.print.XSpan {
1.1	255	font-size: 18pt;
	256	font-family: serif;
	257	}
	258	{{/code}}
	259
28.7	260	Most properties do not require this, however.
1.1	261
28.7	262	=== Enforce page break ===
1.1	263
28.7	264	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//.
1.1	265
4.1	266	{{code language="css"}}
28.7	267	[xn=div2] {
	268	display: block !important;
	269	page-break-before: always;
4.1	270	}
	271	{{/code}}
	272
28.7	273	=== Avoid page break ===
5.1	274
28.7	275	The default setting for printing is that a page break is inserted after each page of the form:
5.1	276
	277	{{code language="css"}}
	278	@media print {
	279	.CXPage:not(:first-child ), .page-break {
	280	display: block !important;
	281	page-break-before: always;
	282	}
	283	}
	284	{{/code}}
	285
28.7	286	In order to avoid breaks, the following rule needs to be defined in the CSS tab of the form:
5.1	287
	288	{{code language="css"}}
	289	@media print {
	290	.CXPage:not(:first-child ) {
	291	page-break-before: avoid;
	292	}
	293	}
	294	{{/code}}
	295
28.7	296	=== Usage of other fonts ===
4.1	297
28.7	298	==== Technical requirements ====
4.1	299
28.7	300	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.
3.1	301
28.7	302	==== Inclusion via CSS ====
1.1	303
28.7	304	To include a font installed on the server for printing, it must be explicitly defined with a {{code language="none"}}@media print{{/code}} query and set for use by the appropriate form elements. In the simplest case, this can look like the following example:
1.1	305
	306	{{code language="css"}}
	307	@media print {
	308	@font-face {
	309	font-family: 'DejaVu Sans';
	310	src: local('DejaVu Sans');
	311	}
	312	.xm-form.modern , .modern .XPage {
	313	font-family: "DejaVu Sans";
	314	}
	315	}
	316	{{/code}}
	317
28.7	318	Here it is especially important that the identifier entered at {{code language="none"}}local(){{/code}} corresponds to the name of the font.
1.1	319
28.7	320	==== Legal notice ====
1.1	321
28.7	322	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.
1.1	323
28.7	324	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.
16.1	325
28.7	326	== JavaScript adjustments ==
16.4	327
28.7	328	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:
16.4	329
	330	{{code language="text"}}
	331	function onPrint(callback: () => Promise<void> \| void): void
	332	{{/code}}
	333
28.7	334	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)//).
16.4	335
28.7	336	For example, to run an AJAX request and wait for it to finish before the form is printed:
16.4	337
	338	{{js}}
	339	$.xutil.onPrint(async () => {
	340	const response = await fetch("http://some-url.de");
	341	// do something with response
	342	});
	343	{{/js}}
	344
	345	{{jsIE}}
	346	$.xutil.onPrint(function() {
	347	return new Promise(function(resolve, reject) {
	348	$.ajax("http://some-url.de", {
	349	success: function(data, textStatus, jqXHR) {
	350	// Do something with the response data
	351	resolve(undefined);
	352	},
	353	error: function(jqXHR, textStatus, errorThrown) {
	354	reject("HTTP request error: " + textStatus + " - " + errorThrown);
	355	},
	356	});
	357	});
	358	});
	359	{{/jsIE}}
	360
28.7	361	== Changelog ==
16.1	362
17.1	363	=== Plugin ===
16.8	364
28.4	365	==== 4.3.1 ====
	366
28.7	367	* fix: Always show the selected appointment date, if any, regardless of the print mode
28.4	368
26.2	369	==== 4.3.0 ====
	370
28.7	371	* feature: New option to retry printing in case of a failure
26.2	372
17.1	373	==== 4.2.3 ====
16.12	374
28.7	375	* Fix: Special characters in combobox select options are now displayed correctly in the printed PDF document
16.12	376
17.1	377	==== 4.2.2 ====
16.10	378
28.7	379	* 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.
16.10	380
17.1	381	==== 4.2.1 ====
16.9	382
28.7	383	* Fix: Show correct version of the print server when performing a check
16.8	384
17.1	385	==== 4.2.0 ====
16.1	386
28.7	387	* feature: New option //blank form//
	388	* feature: Add special CSS classes to the //form.xm-form// such as //xm-print//
	389	* 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.
	390	* 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.
	391	* 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.
16.1	392
17.1	393	==== 4.1.2 ====
16.1	394
28.7	395	* Added note regarding //$.xutil.onPrint// to the plugin UI.
16.1	396
17.1	397	==== 4.1.1 ====
16.1	398
28.7	399	* Requires at least {{formcycle/}} 7.0.4.
	400	* change: Note regarding required field is not shown anymore.
	401	* fix: Show the date format immediately
16.1	402
17.1	403	==== 4.1.0 ====
16.1	404
28.7	405	* 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.
	406	* Configured user groups are saved correctly.
16.1	407
17.1	408	==== 4.0.2 ====
16.1	409
28.7	410	* feature: Added a new timeout option that defaults to 30 seconds. When the print service cannot be reached, the workflow may never complete otherwise.
16.1	411
17.1	412	==== 4.0.1 ====
16.1	413
28.7	414	* fix: The PDF document that was created was not attached to the form record (only for the new workflow action).
16.1	415
17.1	416	==== 4.0.0 ====
16.1	417
28.7	418	* Adjustments for {{formcycle/}} version 7.
16.1	419
17.1	420	=== Server ===
16.1	421
28.5	422	==== 1.7.2 ====
	423
28.7	424	* Close alert messages when any are opened by JavaScript. Otherwise the print can never finish successfully.
28.5	425
	426	==== 1.7.1 ====
	427
28.7	428	* Update install scripts for Linux
28.5	429
28.1	430	==== 1.7.0 ====
27.2	431
28.7	432	* 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.
27.2	433
26.3	434	==== 1.6.1 ====
26.2	435
	436	* Fix compatibility with Windows service installation script
	437
26.3	438	==== 1.6.0 ====
26.2	439
28.7	440	* Update puppeteer to latest version, which uses Chromium 108.0.5351.0
	441	* Add CLI flag //~-~-disableCache=true// to disable the browser cache--
	442	* Add CLI flag //~-~-isolatedBrowser=true// to use a new browser instance for each request.--
	443	* Fix Debian install script, install libgbm1.
26.2	444
17.1	445	==== 1.5.1 ====
16.11	446
28.7	447	* Update node-windows dependency
16.11	448
17.1	449	==== 1.5.0 ====
16.1	450
28.7	451	* Update to Chromium 105.0.5173.0
	452	* Requires at least Node.JS version 14 or higher
16.1	453
17.1	454	==== 1.4.1 ====
16.1	455
28.7	456	* Fix windows service install / uninstall script (//install-windows-service.js// and //uninstall-windows-service.js//)
16.1	457
17.1	458	==== 1.4.0 ====
16.1	459
28.7	460	* When an error occurs while printing, that error is returned as part of the HTTP response
	461	* 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.
	462	* The ///pdf// endpoint without parameters returns a quick summary of the server status