User Tokens¶

With the user token feature, we give the advanced user the possibility to define own tokens directly in the original document. The original files will be analysed for user tokens, which will be removed from the document after extracting the value.

Note

This feature is available in our PDFCreator Business Editions

Please activate this feature when you intend to use it because the search for user tokens might be time consuming on slower PCs.

This feature must be enabled in every profile setting in which you want to use it.

Usage¶

Note

Please note that user tokens are different than regular tokens. The former allow you to define your own tokens in the original document.

Place a user token in your document with the following syntax:

[[[NameOfToken:User token value]]]

The name can be chosen completely free and independent from the regular tokens.

Note

The user token name must not contain blank spaces. Further, the user token name or value may not contain certain characters unless they are escaped.

Please refer to the Special Characters and Backslashes section for more information.

When the user token feature is activated, it will be evaluated and removed from the original document.

Note

User tokens should be placed on separate lines because the whole line will be removed during the process.

Warning

It is recommended that the user tokens are kept to one token per line, because certain applications (e.g. Microsoft Word) sometimes result in unpredictable formatting of the content.

In PDFCreator, you can define user tokens the same way as regular tokens. The token name is composed of the keyword “User:” and the name of the token:

<User:NameOfToken>

In case the document does not include a used user token, the following syntax allows you to set a default value:

<User:NameOfToken:Default value>

Note

The default value is not used if the user token is present in the document but its value remains empty. [[[NameOfToken:]]] would be replaced with an empty string.

Special Characters and Backslashes¶

The value of a user token may contain special characters that need to be escaped with a backslash. For example, escaped characters allow to define paths to folders within a user token.

The following characters need to be escaped:

<, >, {, }, [, ], (, ), :

To ensure proper handling of backslash characters and escape sequences in your input document, it’s important to follow these guidelines.

Every special character in the token value needs to be preceded by a backslash character.

This tells the parser that the following character should be treated differently and not as part of the syntax.

Single backslash characters in your input document that are not immediately followed by a special character, will remain in the token together with the character that follows.

Warning

The following token

[[[PartialPath:Desktop\Folder\]]]

results in escaping one of the three ] characters that signify the ending of a token to the system.
This means that the user token is not parsed correctly.

When the desired outcome is having a backslash character at the end of the token value, the correct way to define the token is the following:

[[[PartialPath:Desktop\Folder\\]]]

Ending the token with two backslashes (rather than one) ensures that there is a single backslash character present at the end of the token value.

Note

It’s worth noting that if you use a special character without a preceding single backslash, the token may not be parsed correctly. In such cases, the system may not recognize the intended escape sequence and treat it as syntax instead.

An example of the mistake:

[[[Path:C:\Users\User\Desktop]]]

The second colon character is invalid user token syntax for the parser, and it fails to parse the token.

In the following example the colon character is escaped correctly and used in the value of the user token instead of being a name and value separator in the token syntax.

[[[Path:C\:\Users\User\Desktop]]]

Usability¶

Just like the regular tokens, user tokens can be used in the following fields:

Title
Author
Stamp Text
Filename Template
Folder Template (for save file dialog)
Target folder (for automatic saving)
E-mail recipients
E-mail subject
E-mail text
Script file path
Script parameters
FTP server directory

Tip

Don’t hesitate to contact us, if your use case is not covered (support@pdfforge.org).

Testing the Workflow¶

In order to test if a user token has been configured correctly, you can run a test conversion via the PDFCreator Test Page button, which you find under the Profiles tab.

The PDFCreator Test Page contains the following token:

[[[TestUserToken:User Token Value]]]

This token is placed in the test page to allow the testing of user token configurations. You can access its value by using <User:TestUserToken> in any of the fields mentioned above.

Once the PDFCreator test page has been created, the removal of the token from the content of the output document, and the presence of the value in the chosen field signifies that the user token action and settings have been set up correctly.

Split Token¶

A Split Token is a special kind of user token that allows to excplicitly define where a document is split. This means that an input document with a single split token would result in two output documents. The syntax of the split token is as follows:

Document 1
[[[SPLIT]]]

--- end of page
Document 2

Note

The split token works on a page-by-page basis, i.e. if there are no subsequent pages, the split token is simply removed without creating another document. In order for it to work it needs a least one additional page after the token.

Note

Upon detection of a split token, not only is the input document’s content split but its user tokens are as well. This means that the user tokens detected before the splitting of the document will only be usable in the job that processes the first output document (whose content is before the split token). Further, if any user tokens were present in the input document after document was split, the values of those tokens would only be accesible from within the job processing the second output document.