RTF Document

Tags in the template

The RTF template can contain the following tags:

<#XXX#>
Normal tag that is replaced by the value in the column with the same name, i.e. XXX. Values such as dates and decimals should be formatted in the procedure and returned as varchars for consistent formatting. Tags can also contain special data like images (see further below).

All values are treated as RTF literals. That means that you can emit, for example, a \page command directly into the document. It also means that you need to use the SoftadminUtil.RTF_Escape function if you need to emit strings containing characters like '{', '}' or ''.

<#$$XXX#>...</#$$XXX#>
Section that surrounds a normal tag. If the value in the column XXX is NULL or missing then the entire section is skipped from the final document.

<##YYY##>...</##YYY##>
Container that is repeated 0-n times depending on the resultset. Each normal tag within the container corresponds to a column in a resultset.

<$$##YYY##>...</$$##YYY##>
Section that surrounds a container (with the same name). If zero rows are returned from the container SQL-statement, then the entire section is skipped from the final document.

Images

For any normal tag where the database returns varbinary data, the data will be assumed to be either a PNG or JPG image and inserted into the document as such. The document will use the image's original resolution when printed.

QR Codes

For any normal tag where the database returns XML data with the root element QrCode a QR Code will be rendered and inserted into the document.

<QrCode cm="3.14">MyQrCode</QrCode>

The element accepts a single (optional) attribute, cm which specifies how large the code should be in centimeters. Do note that this size includes the mandatory quiet zone surrounding the QR code.

Swiss QR Codes

The Swiss QR Code symbology has been developed in Switzerland to automate digital payments. All payment receipts and bills in Switzerland are intended to have a Swiss QR Code barcode that encrypts payment details. To distinguish from basic QR Code, Swiss QR Code labels have the Swiss cross sign in the center.

Example-XML that will render a Swiss QR Code:

<QrCode Type="Swiss">
	<Currency>EUR</Currency>
	<Iban>CH4431999123000889012</Iban>
	<Creditor>
		<AddressType>S</AddressType>
		<Name>John Doe</Name>
		<ZipCode>3003</ZipCode>
		<City>Bern</City>
		<Country>CH</Country>
		<Street>Parlamentsgebäude</Street>
		<HouseNumber>1</HouseNumber>
	</Creditor>
	<Reference>210000000003139471430009017</Reference>
	<AdditionalInformation>
		<UnstructuredMessage>An unstructured message.</UnstructuredMessage>
		<BillInformation>Some bill information here.</BillInformation>
	</AdditionalInformation>
	<Amount>136.19</Amount>
	<Debitor>
		<AddressType>K</AddressType>
		<Name>Multisoft AB</Name>
		<Country>SE</Country>
		<AddressLine1>Brunkebergstorg 5</AddressLine1>
		<AddressLine2>11151 Stockholm</AddressLine2>
	</Debitor>
	<RequestedDateOfPayment>2022-12-30</RequestedDateOfPayment>
</QrCode>

The tags Currency, Iban and Creditor are mandatory. Contact address types are "S" for structured address and "K" for combined address (kombinierte Adresse).

Component settings

SQL

Custom access control and logging

Examples

Informing the user of invalid container names

If you allow end users to administer their own templates then they will occassionally create templates with misspelled or completely unsupported containers. You can use RAISERROR prefixed with ADMIN_MESSAGE to display an error message to the user trying to use the broken template.

ALTER PROCEDURE Examples.RtfWithInvalidContainers
	@Template  bit = 0,
	@Container sysname = NULL
AS
BEGIN
	IF @Container IS NOT NULL
	BEGIN
		IF @Container = 'Container1'
		BEGIN
			SELECT 1 AS ValueInContainer;
			RETURN 0;
		END;

		IF @Container = 'Container2'
		BEGIN
			SELECT 2 AS ValueInContainer;
			RETURN 0;
		END;

		DECLARE @TemplateName varchar(300) = 'ExampleTemplate';

		RAISERROR('ADMIN_MESSAGEThe template %s contains an unsupported container %s.', 16, 1, @TemplateName, @Container);
		RETURN -1;
	END;

Best practice

Create template

Keep it simple, if the needed features are supported, create/save the template in WordPad instead of Word to get a less bloated template. This makes the documents smaller, faster to generate and less prone to errors.

Tables

When creating tables with a container tag the start container should be put in column 1 of the table, and the end container tag should be put after the table.

This should result in this order of data in the rtf file:
\trowd
\pard\intbl <##Container##>\cell\row
\pard </##Container##>