Creating a PDFreactor Instance

To convert a document to PDF or image, you first have to create a PDFreactor instance. This is done with the constructor of the PDFreactor class.

A PDFreactor instance is designed to be reusable, so you only have to create it once. Web service clients require one instance per service.

PDFreactor pdfReactor = new PDFreactor();

PDFreactor pdfReactor = new PDFreactor();

$pdfReactor = new PDFreactor();

pdfReactor = PDFreactor()

pdfReactor = PDFreactor.new()

const pdfReactor = new PDFreactor();

const pdfReactor = new PDFreactor();

Configuring the Conversion

Now that you have a PDFreactor instance , you have to pass configuration properties to PDFreactor. Configuration instances are designed to be one-use, and it is not recommended to use the same configuration instance for multiple conversions.

Configuration config = new Configuration();

Configuration config = new Configuration();

$config = [];

config = {}

config = {}

const config = {};

const config = {};

Specifying the Input Document

PDFreactor can convert a source document in HTML or XML format to PDF or image, depending on the licensed options. Since you already have a configuration from the previous chapter, you can pass the input document with the document configuration property. This property is the only one which actually required (all other configuration properties are optional), and the conversion will fail if it is not set.

The document configuration property is polymorphic and takes a string in various formats, such as a HTML document or a URL. Depending on the integration or client used, it may support other data types. The following table highlights some of the most common use cases for the source document and shows what data types are usually most appropriate. Examples follow after the table.

* Binary data is represented as a byte array (byte[]) in Java and .NET, and as a base64-encoded string in other service clients.

config.setDocument("file:///local-folder/document.html");    // Linux/Mac
config.setDocument("file:///c:/local-folder/document.html"); // Windows

config.Document = "file:///local-folder/document.html";    // Linux/Mac
config.Document = "file:///c:/local-folder/document.html"; // Windows

$config["document"] = "file:///local-folder/document.html";    // Linux/Mac
$config["document"] = "file:///c:/local-folder/document.html"; // Windows

config['document'] = "file:///local-folder/document.html"    # Linux/Mac
config['document'] = "file:///c:/local-folder/document.html" # Windows

config['document'] = "file:///local-folder/document.html"    # Linux/Mac
config['document'] = "file:///c:/local-folder/document.html" # Windows

config.document = "file:///local-folder/document.html";    // Linux/Mac
config.document = "file:///c:/local-folder/document.html"; // Windows

config.document = "file:///local-folder/document.html";    // Linux/Mac
config.document = "file:///c:/local-folder/document.html"; // Windows

{ "document": "file:///local-folder/document.html" }

{ "document": "file:///c:/local-folder/document.html" }

config.setDocument("https://some-server.com/document.html");

config.Document = "https://some-server.com/document.html";

$config["document"] = "https://some-server.com/document.html";

config['document'] = "https://some-server.com/document.html"

config['document'] = "https://some-server.com/document.html"

config.document = "https://some-server.com/document.html";

config.document = "https://some-server.com/document.html";

{ "document": "https://some-server.com/document.html" }

String renderedTemplate = renderMyTemplate();
config.setDocument(renderedTemplate);

String renderedTemplate = RenderMyTemplate();
config.Document = renderedTemplate;

$renderedTemplate = $renderMyTemplate();
$config["document"] = $renderedTemplate;

renderedTemplate = renderMyTemplate()
config['document'] = renderedTemplate

renderedTemplate = renderMyTemplate()
config['document'] = renderedTemplate

const renderedTemplate = renderMyTemplate();
config.document = renderedTemplate

const renderedTemplate = renderMyTemplate();
config.document = renderedTemplate

{ "document": "<html><body><p>My rendered template</p></body></html>" }

The document configuration property is required, all other configuration properties are optional.

Starting the Conversion

Now that you have created your configuration by at least specifying an input document, you can start the conversion. This is explained in detail in the integration-specific chapter:

• Synchronous and asynchronous conversions in a PDFreactor Web Service client

Processing the Result

Once the conversion is finished, you either receive a Result object, the converted document as raw bytes, or other API-specific data types. In this chapter, we will focus on the Result object as it not only contains the converted document but also other conversion-specific metadata that may be useful for integrators. It contains the following properties:

The result document can be accessed like this:

byte[] pdfOrImage = result.getDocument();
byte[][] imagePages = result.getDocumentArray();

byte[] pdfOrImage = result.Document;
byte[][] imagePages = result.DocumentArray;

$pdfOrImage = $result->document;
$imagePages = $result->documentArray;

pdfOrImage = result['document'];
imagePages = result['documentArray'];

pdfOrImage = result["document"]
imagePages = result["documentArray"]

const pdfOrImage = result.document;
const imagePages = result.documentArray;

const pdfOrImage = result.document;
const imagePages = result.documentArray;

$.document
$.documentArray

Note that the result object has either a document or a documentArray depending on the specified output format, but never both. In most scenarios, converted documents need to be processed further by the integrator's own business logic.

Please refer to the API documentation of the client or integration for more details and on how to access these properties.

Parallel Conversions

When doing multiple parallel PDF conversions, it is important to adapt the available memory to the number of parallel conversions.

Generally, a common document requires no more than 64MB of memory. To safely convert up to 16 of these documents in parallel, PDFreactor requires at least 1GB of memory (16 * 64MB). Keep in mind that this is merely a rule of thumb and that the amount of required memory may vary depending on the documents and integration environments.

Extensive Conversions

Most commonly, memory is the limiting factor when trying to convert very large or complex documents. Besides increasing the amount of memory, PDFreactor offers other strategies you could employ which will reduce memory pressure. See for general recommendations on how to convert particularly large jobs.

Analyzing Memory Consumption

When converting documents with PDFreactor, Java will consume certain amounts of memory (depending on the size and complexity of the document), up to its configured maximum heap size. Should it run out of free available memory, the Java VM will perform a so-called garbage collection. This will free up unused memory.

However, if a conversion is finished, Java actually won't automatically perform a garbage collection as it is not necessary. When using non-Java system tools to inspect memory usage, this behavior may appear problematic since Java seems to retain more and more memory without freeing it up even if there are currently no conversions running. Nevertheless, this is normal and intended Java behavior.

Java only frees up memory if necessary and won't do so merely because a process such as a PDFreactor conversion ends. This means memory issues can't reliably be analyzed using non-Java system tools since they don't actually show how much memory can be freed up after a garbage collection.

To properly analyze memory issues, we recommend Java-specific tools like VisualVMhttps://github.com/oracle/visualvm.

Conversion Name

You can specify an arbitrary name for each conversion using the conversionName configuration property. This name will be logged as the first and last line in each conversion log. This makes it easy to match a conversion log to a particular document.

Log Capacity

During the course of the conversion, PDFreactor stores several messages in internal logs so that they can be accessed afterwards. Those internal logs have a limited capacity. By default, each log stores 100 000 entries. This should be sufficient for most documents. In the rare cases where this number needs to be adjusted, you can use the configuration property logMaxLines like this:

config.setLogMaxLines(100);

config.LogMaxLines = 100;

$config["logMaxLines"] = 100;

config['logMaxLines'] = 100

config['logMaxLines'] = 100

config.logMaxLines = 100;

config.logMaxLines = 100;

{ "logMaxLines": 100 }

If the log capacity is exceeded, the oldest entries will be removed to make room for the new ones.

Evaluation Mode

Without a license key PDFreactor runs in evaluation mode. In evaluation mode it is possible to integrate and test PDFreactor just like the full version but the resulting PDF document will include watermarks and additional evaluation pages.

Receiving a License Key

To obtain a license key, please visit the PDFreactor website (https://www.pdfreactor.com). It provides information about all available licenses and how to receive license keys.

Setting the License Key

RealObjects provides you a license key file in XML format.

The license key can be set as a string using the licenseKey configuration property.

String licensekey = "<license>... your license ...</license>";
config.setLicenseKey(licensekey);

string licensekey = "<license>... your license ...</license>";
config.LicenseKey = licensekey;

$licensekey = "<license>... your license ...</license>";
$config["licenseKey"] = $licensekey;

licensekey = "<license>... your license ...</license>"
config['licenseKey'] = licensekey

licensekey = "<license>... your license ...</license>"
config['licenseKey'] = licensekey

const licensekey = "<license>... your license ...</license>";
config.licenseKey = licensekey;

const licensekey = "<license>... your license ...</license>";
config.licenseKey = licensekey;

{ "licenseKey": "<license>... your license ...</license>" }

config.setErrorPolicies(ErrorPolicy.LICENSE);

config.ErrorPolicies = new List<ErrorPolicy> { ErrorPolicy.LICENSE };

$config["errorPolicies"] = array(ErrorPolicy::LICENSE);

config['errorPolicies'] = [ PDFreactor.ErrorPolicy.LICENSE ]

config['errorPolicies'] = [ PDFreactor::ErrorPolicy::LICENSE ]

config.errorPolicies = [ PDFreactor.ErrorPolicy.LICENSE ];

config.errorPolicies = [ PDFreactor.ErrorPolicy.LICENSE ];

{ "errorPolicies": [ "LICENSE" ] }

Exceeding Content

Content that does not fit into its pages can be logged as well as programmatically analyzed. This functionality is enabled and configured by using the content observer and requires two arguments:

For example:

contentObserver
    .setExceedingContentAnalyze(ExceedingContentAnalyze.CONTENT_AND_STATIC_BOXES)
    .setExceedingContentAgainst(ExceedingContentAgainst.PAGE_CONTENT);

contentObserver.ExceedingContentAnalyze = ExceedingContentAnalyze.CONTENT_AND_STATIC_BOXES;
contentObserver.ExceedingContentAgainst = ExceedingContentAgainst.PAGE_CONTENT;

$contentObserver["exceedingContentAnalyze"] = ExceedingContentAnalyze::CONTENT_AND_STATIC_BOXES;
$contentObserver['exceedingContentAgainst"] = ExceedingContentAgainst::PAGE_CONTENT;

contentObserver['exceedingContentAnalyze'] = PDFreactor.ExceedingContentAnalyze.CONTENT_AND_STATIC_BOXES
contentObserver['exceedingContentAgainst'] = PDFreactor.ExceedingContentAgainst.PAGE_CONTENT

contentObserver['exceedingContentAnalyze'] = PDFreactor::ExceedingContentAnalyze::CONTENT_AND_STATIC_BOXES
contentObserver['exceedingContentAgainst'] = PDFreactor::ExceedingContentAgainst::PAGE_CONTENT

contentObserver.exceedingContentAnalyze = PDFreactor.ExceedingContentAnalyze.CONTENT_AND_STATIC_BOXES;
contentObserver.exceedingContentAgainst = PDFreactor.ExceedingContentAgainst.PAGE_CONTENT;

contentObserver.exceedingContentAnalyze = PDFreactor.ExceedingContentAnalyze.CONTENT_AND_STATIC_BOXES;
contentObserver.exceedingContentAgainst = PDFreactor.ExceedingContentAgainst.PAGE_CONTENT;

{ "exceedingContentAnalyze": "CONTENT_AND_STATIC_BOXES",
  "exceedingContentAgainst": "PAGE_CONTENT" }

To programmatically process the results you can get an array of ExceedingContent objects using the property exceedingContents. Please see the API documentation for details on this class.

ExceedingContent[] exceedingContents = result.getExceedingContents();

ExceedingContent[] exceedingContents = result.ExceedingContents;

$exceedingContents = $result->exceedingContents;

exceedingContents = result['exceedingContents'];

exceedingContents = result["exceedingContents"]

const exceedingContents = result.exceedingContents;

const exceedingContents = result.exceedingContents;

$.exceedingContents

Missing Resources

To ensure that all resources referenced in the input document (or in other resources) are loaded, configure the content observer like this:

contentObserver.setMissingResources(true);

contentObserver.MissingResources = true;

$contentObserver["missingResources"] = true;

contentObserver['missingResources'] = True

contentObserver['missingResources'] = true

contentObserver.missingResources = true;

contentObserver.missingResources = true;

{ "missingResources": true }

After the conversion, you can access and analyze a log containing all missing resources using the property missingResources. It returns an array of MissingResource objects which contains the resource description, type (e.g. style sheet, image, etc.) as well as a description why the resource is missing. If the log is null, no resources are missing. Please see the API documentation for details on this class.

MissingResource[] missingResources = result.getMissingResources();

MissingResource[] missingResources = result.MissingResources;

$missingResources = $result->missingResources;

missingResources = result['missingResources'];

missingResources = result["missingResources"]

const missingResources = result.missingResources;

const missingResources = result.missingResources;

$.missingResources

Connections

It is also possible to log all connections or connection attempts performed by PDFreactor. For this, configure the content observer like this:

contentObserver.setConnections(true);

contentObserver.Connections = true;

$contentObserver["connections"] = true;

contentObserver['connections'] = True

contentObserver['connections'] = true

contentObserver.connections = true;

contentObserver.connections = true;

{ "connections": true }

A log containing all connections or connection attempts can be accessed after the conversion via the connections property. It returns an array of Connection objects which contain data about the connection. For HTTP connections, the data includes the status code as well as request and response headers. Please see the API documentation for details on this class.

Connection[] connections = result.getConnections();

Connection[] connections = result.Connections;

$connections = $result->connections;

connections = result['connections'];

connections = result["connections"]

const connections = result.connections;

const connections = result.connections;

$.connections

Please note that connections that were blocked due to security settings are not included in this log since PDFreactor blocked the connection before even attempting to open it.

Debug Settings

When integrating PDFreactor, especially during the trial and development phases, it might be useful to retrieve debugging information about the conversion. The most convenient way to do this is by enabling the various debugging tools of PDFreactor. This can be done in the configuration like this:

config.setDebugSettings(new DebugSettings().setAll(true));

config.DebugSettings = new DebugSettings { All: true };

$config["debugSettings"] = array("all" => true);

config['debugSettings'] = { "all": True }

config['debugSettings'] = { "all": true }

config.debugSettings = { all: true };

config.debugSettings = { all: true };

{ "debugSettings": { "all": true }}

This causes PDFreactor to do the following:

• Set the log level to the most verbose level, i.e. LogLevel.PERFORMANCE.

• Append logs to the generated PDF with that log level. Can be controlled with the appendLogs property of the DebugSettings object.

• Attach various debug files to the generated PDF. Can be controlled with the attachConfiguration, attachDocuments, attachResources, and attachLogs properties of the DebugSettings object.

• No longer throw any exceptions. Instead, in case of an exception, a text document is returned that contains the conversion log as well as the exception that would have been thrown. Can be controlled with the forceResult property of the DebugSettings object.

The following debug files are attached by default:

PDFreactor-dump-yyyy-MM-dd-HH-mm-ss-SSS

Inspectable Documents

To create inspectable documents that can be used with the PDFreactor Inspector application, use the inspectableSettings configuration option like this:

config.setInspectableSettings(new InspectableSettings()
    .setEnabled(true));

config.InspectableSettings = new InspectableSettings
{
    Enabled = true
};

config.inspectableSettings = {
    enabled: true
};

config.inspectableSettings = {
    enabled: true
};

$config["inspectableSettings"] = array(
    "enabled" => true
);

config['inspectableSettings'] = {
    'enabled': True
}

config['inspectableSettings'] = {
    enabled: true
}

{ "inspectableSettings": {
    "enabled": true
}}

Trusted and Untrusted Contexts

PDFreactor distinguishes between two security contexts when applying the security settings: Trusted and untrusted. The PDFreactor API (i.e. the configuration object that is passed to the convert methods) is considered a trusted security context, because usually only integrators have access to it. Any documents or resources that are specified there are not subject to the connection security. So no matter how you configure the connection security settings, resources specified in configuration properties such as document, userStyleSheets, baseUrl etc. are always allowed because it is assumed they have been set by the integrator.

Please note that this is not transitive. Even though user style sheets and user scripts are always allowed, resources that they load, e.g. via "@import" rule or XHR are subject to the connection security.

System fonts can also always be loaded, however they can be disabled separately.

All other resources, especially those that are part of the input document which is potentially produced by untrusted third parties, are vetted according to the configured security settings.

config.setSecuritySettings(new SecuritySettings()
    .setUntrustedApi(true));

config.setSecuritySettings(new SecuritySettings()
    .setAllowAuthorApiOverrides(true));

Automatic Redirects

By default, PDFreactor follows redirects automatically. You can disable this with the allowRedirects property:

Connection Rules

You can define security rules that either deny or allow connections to certain resources. These rules support wildcard patterns for their hosts and paths. Each rule also has a priority. Rules are evaluated in order of their priority, starting with the highest priority value. If rules have the same priority, they are evaluated in the same order as they were inserted in the API. The priority is 0 by default.

If a resource is not matched by any of the rules (or if there are no rules), the default security behavior is applied.

If multiple resource properties of a rule such as protocol, host, port or path are specified, the resource must match all of the defined properties.

/part/../resource path/file?param=value#fragment

/resource%20path/file

[{
    "action": "ALLOW",
    "name": "Allow internal company CMS",
    "host": "company-cms"
    }, {
    "action": "ALLOW",
    "name": "Allow public company CDN",
    "protocol": "https",
    "host": "cdn.company.com",
    "path": "/public%20assets/**"
    }, {
    "action": "DENY",
    "name": "Deny all",
    "path": "/**",
    "priority": -1
}]

[{
    "action": "ALLOW",
    "name": "Allow internal company CMS",
    "host": "company-cms"
    }, {
    "action": "ALLOW",
    "name": "Allow public company CDN",
    "protocol": "https",
    "host": "cdn.company.com",
    "path": "/public%20assets/**"
    }, {
    "action": "DENY",
    "name": "Deny all",
    "path": "/**",
    "priority": -1
}]

[{
    "action": "ALLOW",
    "name": "Allow internal company CMS",
    "host": "company-cms"
    }, {
    "action": "ALLOW",
    "name": "Allow public company CDN",
    "protocol": "https",
    "host": "cdn.company.com",
    "path": "/public%20assets/**"
    }, {
    "action": "DENY",
    "name": "Deny all",
    "path": "/**",
    "priority": -1
}]

[{
    "action": "ALLOW",
    "name": "Allow internal company CMS",
    "host": "company-cms"
    }, {
    "action": "ALLOW",
    "name": "Allow public company CDN",
    "protocol": "https",
    "host": "cdn.company.com",
    "path": "/public%20assets/**"
    }, {
    "action": "DENY",
    "name": "Deny all",
    "path": "/**",
    "priority": -1
}]

[{
    "action": "ALLOW",
    "name": "Allow internal company CMS",
    "host": "company-cms"
    }, {
    "action": "ALLOW",
    "name": "Allow public company CDN",
    "protocol": "https",
    "host": "cdn.company.com",
    "path": "/public%20assets/**"
    }, {
    "action": "DENY",
    "name": "Deny all",
    "path": "/**",
    "priority": -1
}]

[{
    "action": "ALLOW",
    "name": "Allow internal company CMS",
    "host": "company-cms"
    }, {
    "action": "ALLOW",
    "name": "Allow public company CDN",
    "protocol": "https",
    "host": "cdn.company.com",
    "path": "/public%20assets/**"
    }, {
    "action": "DENY",
    "name": "Deny all",
    "path": "/**",
    "priority": -1
}]

[{
    "action": "ALLOW",
    "name": "Allow internal company CMS",
    "host": "company-cms"
    }, {
    "action": "ALLOW",
    "name": "Allow public company CDN",
    "protocol": "https",
    "host": "cdn.company.com",
    "path": "/public%20assets/**"
    }, {
    "action": "DENY",
    "name": "Deny all",
    "path": "/**",
    "priority": -1
}]

[{
    "action": "ALLOW",
    "name": "Allow internal company CMS",
    "host": "company-cms"
    }, {
    "action": "ALLOW",
    "name": "Allow public company CDN",
    "protocol": "https",
    "host": "cdn.company.com",
    "path": "/public%20assets/**"
    }, {
    "action": "DENY",
    "name": "Deny all",
    "path": "/**",
    "priority": -1
}]

*.pdfreactor.com

cloud.pdfreactor.com
www.pdfreactor.com

pdfreactor.com
www.cloud.pdfreactor.com

**.pdfreactor.com

/**/*.css

[{
    "action": "DENY",
    "name": "Deny all",
    "path": "/**",
    "priority": -1
}]

[{
    "action": "DENY",
    "name": "Deny all",
    "path": "/**",
    "priority": -1
}]

[{
    "action": "DENY",
    "name": "Deny all",
    "path": "/**",
    "priority": -1
}]

[{
    "action": "DENY",
    "name": "Deny all",
    "path": "/**",
    "priority": -1
}]

[{
    "action": "DENY",
    "name": "Deny all",
    "path": "/**",
    "priority": -1
}]

[{
    "action": "DENY",
    "name": "Deny all",
    "path": "/**",
    "priority": -1
}]

[{
    "action": "DENY",
    "name": "Deny all",
    "path": "/**",
    "priority": -1
}]

[{
    "action": "DENY",
    "name": "Deny all",
    "path": "/**",
    "priority": -1
}]

[{
    "action": "ALLOW",
    "name": "Allow access to resources inside a JAR",
    "protocol": "file",
    "path": "/path/to/my.jar",
    "entry": "/resources/**"
}]

[{
    "action": "ALLOW",
    "name": "Allow access to resources inside a JAR",
    "protocol": "file",
    "path": "/path/to/my.jar",
    "entry": "/resources/**"
}]

[{
    "action": "ALLOW",
    "name": "Allow access to resources inside a JAR",
    "protocol": "file",
    "path": "/path/to/my.jar",
    "entry": "/resources/**"
}]

[{
    "action": "ALLOW",
    "name": "Allow access to resources inside a JAR",
    "protocol": "file",
    "path": "/path/to/my.jar",
    "entry": "/resources/**"
}]

[{
    "action": "ALLOW",
    "name": "Allow access to resources inside a JAR",
    "protocol": "file",
    "path": "/path/to/my.jar",
    "entry": "/resources/**"
}]

[{
    "action": "ALLOW",
    "name": "Allow access to resources inside a JAR",
    "protocol": "file",
    "path": "/path/to/my.jar",
    "entry": "/resources/**"
}]

[{
    "action": "ALLOW",
    "name": "Allow access to resources inside a JAR",
    "protocol": "file",
    "path": "/path/to/my.jar",
    "entry": "/resources/**"
}]

[{
    "action": "ALLOW",
    "name": "Allow access to resources inside a JAR",
    "protocol": "file",
    "path": "/path/to/my.jar",
    "entry": "/resources/**"
}]

jar:file:///path/to/my.jar!/resources/image.png

Default Security Behavior

The default security behavior is applied to any URL to which no connection rule matched. The appropriate configuration properties are grouped in the defaults property of the securitySettings. Checks are applied in the following order:

allowSameBasePath

This property is considered true if not specified.

When a document is converted from URL or a base URL is specified, access to resources within the same base path is allowed. No further security checks will be made for that resource. Please note that this allows for HSTS, i.e. when the base or document URL is HTTP, then resources within the same base path using HTTPS are also allowed.

This check is always skipped if the untrustedApi property is true.

If a resource is within the same base path, it is allowed. Otherwise, subsequent default checks below are applied.

The base path is the normalized part of the URL leading to the input document (or the base URL if specified), up to the last slash. For HTTP or HTTPS URLs, the base Path consists of at least the host, even if the URL does not end with a slash. For file URLs, it is ensured that the base Path is never the root directory.

For example, if the following URL is the input URL of your document:

http://myServer/document.html

Then the base path is the following URL:

http://myServer/

allowProtocols

This property is considered to have the values "http", "https", "data" and "blob" if not specified.

A list of URL protocols (as lower-case strings) that are allowed. If the protocol of a resource is not contained within this list, the resource is not loaded. Note that the "file" protocol is not handled by this setting. Use allowFileSystemAccess to allow or restrict file URLs.

If the resource's protocol is not allowed, the resource is denied. Otherwise, subsequent default checks below are applied.

allowFileSystemAccess

This property is considered false if not specified.

Allows access to the file system. This is prohibited by default.

If a resource points to a file and file system access is not allowed, the resource is denied. Otherwise, subsequent default checks below are applied.

allowAddresses

This property is considered to have the values PUBLIC, PRIVATE and LOCAL if not specified.

Allows connections to a certain type of host or IP address. Possible values are:

• PUBLIC — Public hosts or IP addresses.

• PRIVATE — Hosts in private networks or IP addresses in the private range.

• LOCAL — Hosts or IP addresses pointing to the local machine.

• LINK_LOCAL — Link-local addresses or auto-IPs which are usually assigned automatically and are usually not used to provide any useful resources for the conversion. Unless explicitly required, it is recommended to not grant access to this type of address.

If a resource points to a network address that is not allowed, the resource is denied.

Non-local File URLs

PDFreactor automatically considers all file URLs to be invalid that have an authority component other than "localhost". For example, the file URLs file:///dir/file (no host) and file://localhost/dir/file are considered valid but file://host/dir/file, file://LOCALHOST/dir/file, and file://localhost:8080/dir/file are not.

Enabling this setting allows for arbitrary authority components in file URLs but may cause system-specific behavior. On Windows systems for example, a file URL with a non-local host is interpreted as a UNC path. This might allow potentially malicious authors gain information about the server's OS and available network resources.

Since this affects the creation of URLs, they are checked before any other security checks are made.

Legacy XHTML

It is also possible, albeit discouraged, to enable the legacy XHTML parser and its cleanup processes for HTML documents. You can force this document type like this:

config.setDocumentType(Doctype.XHTML);

config.DocumentType = Doctype.XHTML;

$config["documentType"] = Doctype::XHTML;

config['documentType'] = PDFreactor.Doctype.XHTML

config['documentType'] = PDFreactor::Doctype::XHTML

config.documentType = PDFreactor.Doctype.XHTML;

config.documentType = PDFreactor.Doctype.XHTML;

{ "documentType": "XHTML" }

In legacy XHTML, there are various cleanup tools at your disposal that will attempt to repair non-well-formed XHTML documents:

• CYBERNEKO (default)
• JTIDY
• TAGSOUP
• NONE (no cleanup)

You can set a cleanup tool like this:

config.setCleanupTool(Cleanup.TAGSOUP);

config.CleanupTool = Cleanup.TAGSOUP;

$config["cleanupTool"] = Cleanup::TAGSOUP;

config['cleanupTool'] = PDFreactor.Cleanup.TAGSOUP

config['cleanupTool'] = PDFreactor::Cleanup::TAGSOUP

config.cleanupTool = PDFreactor.Cleanup.TAGSOUP;

config.cleanupTool = PDFreactor.Cleanup.TAGSOUP;

{ "cleanupTool": "TAGSOUP" }

HTML + JavaScript

PDFreactor can also process JavaScript contained or linked in the HTML document. See for further details.

XML + XSLT

PDFreactor can optionally transform XML documents using XSLT style sheets. This can transform the document into other formats such as HTML. As with the normal input document, PDFreactor attempts to detect the document type of the post-transformation document. This can be overridden by using the postTransformationDocumentType.

The configuration property xsltMode is used to enable XSLT processing.

config.setPostTransformationDocumentType(Doctype.HTML5);
config.setXsltMode(true);

config.PostTransformationDocumentType = Doctype.HTML5;
config.XsltMode = true;

$config["postTransformationDocumentType"] = Doctype::HTML5;
$config["xsltMode"] = true;

config['postTransformationDocumentType'] = PDFreactor.Doctype.HTML5
config['xsltMode'] = True

config['postTransformationDocumentType'] = PDFreactor::Doctype::HTML5
config['xsltMode'] = true

config.postTransformationDocumentType = PDFreactor.Doctype.HTML5;
config.xsltMode = true;

config.postTransformationDocumentType = PDFreactor.Doctype.HTML5;
config.xsltMode = true;

{ "postTransformationDocumentType": "HTML5", "xsltMode": true }

Network Settings

PDFreactor automatically loads resources over the network or the local file system via file URLs. The network settings encapsulate configuration options that affect how PDFreactor connects to a server to access a resource and how it behaves when downloading it.

config.setNetworkSettings(new NetworkSettings()
    .setConnectTimeout(1000)
    .setReadTimeout(1000));

config.NetworkSettings = new NetworkSettings
{
    ConnectTimeout = 1000,
    ReadTimeout = 1000
};

$config["networkSettings"] = [
    "connectTimeout" => 1000,
    "readTimeout" => 1000
];

config['networkSettings'] = {
    'connectTimeout': 1000,
    'readTimeout': 1000
}

config['networkSettings'] = {
    'connectTimeout': 1000,
    'readTimeout': 1000
}

config.networkSettings = {
    connectTimeout = 1000,
    readTimeout = 1000
};

config.networkSettings = {
    connectTimeout = 1000,
    readTimeout = 1000
};

{ "networkSettings: {
    "connectTimeout": 1000,
    "readTimeout": 1000
}}

config.setNetworkSettings(new NetworkSettings()
    .setAuthenticationCredentials(new HttpCredentials()
        .setUsername("username")
        .setPassword("password")
        .setAuthScheme(HttpAuthScheme.DIGEST)
        .setRealm("My Realm")));

config.NetworkSettings = new NetworkSettings
{
    AuthenticationCredentials = new List>HttpCredentials<
    {
        new HttpCredentials
        {
            Username = "username",
            Password = "password",
            AuthScheme = HttpAuthScheme.DIGEST,
            Realm = "My Realm"
        }
    }
};

$config["networkSettings"] = [
    "authenticationCredentials" => [
        {
            "username" => "username",
            "password" => "password",
            "authScheme" => HttpAuthScheme::DIGEST,
            "realm" => "My Realm"
        }
    ]
];

config['networkSettings'] = {
    'authenticationCredentials': [
        {
            'username': 'username',
            'password': 'password',
            'authScheme': PDFreactor.HttpAuthScheme.DIGEST,
            'realm': 'My Realm'
        }
    ]
}

config['networkSettings'] = {
    'authenticationCredentials': [
        {
            'username': "username",
            'password': "password",
            'authScheme': PDFreactor::HttpAuthScheme::DIGEST,
            'realm': "My Realm"
        }
    ]
}

config.networkSettings = {
    authenticationCredentials: [
        username: "username",
        password: "password",
        authScheme: PDFreactor.HttpAuthScheme.DIGEST,
        realm: "My Realm"
    ]
};

config.networkSettings = {
    authenticationCredentials: [
        username: "username",
        password: "password",
        authScheme: PDFreactor.HttpAuthScheme.DIGEST,
        realm: "My Realm"
    ]
};

{ "networkSettings: {
    "authenticationCredentials": [
        "username": "username",
        "password": "password",
        "authScheme": "DIGEST",
        "realm": "My Realm"
    ]
}}

config.setNetworkSettings(new NetworkSettings()
    .setRequestHeaders(
        new KeyValuePair("User-Agent", "MyApp/2.0"));

config.NetworkSettings = new NetworkSettings
{
    RequestHeaders = new List<KeyValuePair>
    {
        new KeyValuePair("User-Agent", "MyApp/2.0")
    }
};

$config["networkSettings"] = [
    "requestHeaders": [
    [
        "key" => "User-Agent",
        "value" => "MyApp/2.0"
    ]
);

config['networkSettings'] = {
    'requestHeaders'] = [
        { 'key': "User-Agent", 'value': "MyApp/2.0" }
    ]
}

config['networkSettings'] = {
    'requestHeaders' = [
        { key: "User-Agent", value: "MyApp/2.0" }
    ]
}

config.networkSettings = {
    requestHeaders = [
        { key: "User-Agent", value: "MyApp/2.0" }
    ]
};

config.networkSettings = {
    requestHeaders = [
        { key: "User-Agent", value: "MyApp/2.0" }
    ]
};

{ "networkSettings": {
    "requestHeaders": [
        { "key": "User-Agent", "value": "MyApp/2.0" }
    ]
}}

config.setNetworkSettings(new NetworkSettings()
    .setCookies(new Cookie()
        .setName("JSESSIONID")
        .setValue("123456789")));

config.NetworkSettings = new NetworkSettings
{
    Cookies = new List>Cookie<
    {
        new Cookie
        {
            Name = "JSESSIONID",
            Value = "123456789"
        }
    }
};

$config["networkSettings"] = [
    "cookies" => [
        {
            "name" => "JSESSIONID",
            "value" => "123456789"
        }
    ]
];

config['networkSettings'] = {
    'cookies': [
        {
            'name': 'JSESSIONID',
            'value': '123456789'
        }
    ]
}

config['networkSettings'] = {
    'cookies': [
        {
            'name': "JSESSIONID",
            'value': "123456789"
        }
    ]
}

config.networkSettings = {
    cookies: [
        name: "JSESSIONID",
        value: "123456789"
    ]
};

config.networkSettings = {
    cookies: [
        name: "JSESSIONID",
        value: "123456789"
    ]
};

{ "networkSettings: {
    "cookies": [
        "name": "JSESSIONID",
        "value": "123456789"
    ]
}}

config.setNetworkSettings(new NetworkSettings()
    .setCookiePolicy(CookiePolicy.RELAXED));

config.NetworkSettings = new NetworkSettings
{
    CookiePolicy = CookiePolicy.RELAXED
};

$config["networkSettings"] = [
    "cookiePolicy" => CookiePolicy::RELAXED
];

config['networkSettings'] = {
    'cookiePolicy': PDFreactor.CookiePolicy.RELAXED
}

config['networkSettings'] = {
    'cookiePolicy': PDFreactor::CookiePolicy::RELAXED
}

config.networkSettings = {
    cookiePolicy: PDFreactor.CookiePolicy.RELAXED
};

config.networkSettings = {
    cookiePolicy: PDFreactor.CookiePolicy.RELAXED
};

{ "networkSettings: {
    "cookiePolicy: "RELAXED"
}}

URL Rewrites

PDFreactor can rewrite all URLs before connections to resources are even opened. This is done via the urlRewriteSettings configuration property. This object takes one or more rules according to which URLs are rewritten. The new URLs are then used to open the connections.

URL rewrite rules take a regular expression pattern and a substitution. The substitution can include group identifiers and back references.

config.setUrlRewriteSettings(new UrlRewriteSettings()
    .setRules(
        new UrlRewriteRule()
            .setPattern("^http://myOldHost/(.*)$")
            .setSubstitution("https://myNewHost/$1")        
    )
);

config.UrlRewriteSettings = new UrlRewriteSettings
{
    Rules = new List<Resource>
    {
        new UrlRewriteRule()
        {
            Pattern = "^http://myOldHost/(.*)$",
            Substitution = "https://myNewHost/$1"
        }
    }
};

$config["urlRewriteSettings"] = array(
    "rules" => array(
        array(
            "pattern" => "^http://myOldHost/(.*)$",
            "substitution" => "https://myNewHost/$1"
        )
    )
);

config['urlRewriteSettings'] = {
    'rules': [{
        'pattern': "^http://myOldHost/(.*)$"
        'substitution': "https://myNewHost/$1"
    }]
}

config['urlRewriteSettings'] = {
    rules: [{
        pattern: "^http://myOldHost/(.*)$",
        substitution: "https://myNewHost/$1"
    }]
}

config.urlRewriteSettings = {
    rules: [{
        pattern: "^http://myOldHost/(.*)$",
        substitution: "https://myNewHost/$1"
    }]
};

config.urlRewriteSettings = {
    rules: [{
        pattern: "^http://myOldHost/(.*)$",
        substitution: "https://myNewHost/$1"
    }]
};

{ "urlRewriteSettings": {
    "rules": [{
        "pattern": "^http://myOldHost/(.*)$",
        "substitution": "https://myNewHost/$1"
    }]
}}

All URLs that are called by PDFreactor are matched agains all URL rewrite rules. The URLs that are being matched are always absolute and normalized. This means that:

• If the original URL was not absolute, it is resolved against the document's base URL

• All non-URI characters are URL encoded

• Dot segments are resolved or removed

Otherwise the URL is matched as-is, including query parameters and userinfo.

User Style Sheets

User style sheets represent CSS that is loaded in addition to the CSS specified in the input document. Generally, user style sheets have higher priority as document style sheets, but lower priority as inline styles.

They can be added like this:

config.setUserStyleSheets(
    new Resource().setContent("p { color: red; }"),
    new Resource().setUri("http://myServer/my.css"));

config.UserStyleSheets = new List<Resource>
{
    new Resource() { Content = "p { color: red; }" },
    new Resource() { Uri = "http://myServer/my.css" }
};

config.userStyleSheets = [
    { content: "p { color: red; }" },
    { uri: "http://myServer/my.css" }
];

config.userStyleSheets = [
    { content: "p { color: red; }" },
    { uri: "http://myServer/my.css" }
];

$config["userStyleSheets"] = array(
    array("content" => "p { color: red; }"),
    array("uri" => "http://myServer/my.css")
);

config['userStyleSheets'] = [
    { 'content': 'p { color: red; }' },
    { 'uri': 'http://myServer/my.css' }
]

config['userStyleSheets'] = [
    { 'content': 'p { color: red; }' },
    { 'uri': 'http://myServer/my.css' }
]

{ "userStyleSheets": [
    { "content": "p { color: red; }" },
    { "uri": "http://myServer/my.css" }
]}

Integration Style Sheets

Integration style sheets are similar to user style sheets, but they have a lower priority than document CSS, and thus also a lower priority than user style sheets.

config.setIntegrationStyleSheets(
    new Resource().setContent("p { font-family: sans-serif }"),
    new Resource().setUri("http://myServer/corporate-identity.css"));

config.IntegrationStyleSheets = new List<Resource>
{
    new Resource() { Content = "p { font-family: sans-serif }" },
    new Resource() { Uri = "http://myServer/corporate-identity.css" }
};

config.integrationStyleSheets = [
    { content: "p { font-family: sans-serif }" },
    { uri: "http://myServer/corporate-identity.css" }
];

config.integrationStyleSheets = [
    { content: "p { font-family: sans-serif }" },
    { uri: "http://myServer/corporate-identity.css" }
];

$config["integrationStyleSheets"] = array(
    array("content" => "p { font-family: sans-serif }"),
    array("uri" => "http://myServer/corporate-identity.css")
);

config['integrationStyleSheets'] = [
    { 'content': 'p { font-family: sans-serif }' },
    { 'uri': 'http://myServer/corporate-identity.css' }
]

config['integrationStyleSheets'] = [
    { 'content': 'p { font-family: sans-serif }' },
    { 'uri': 'http://myServer/corporate-identity.css' }
]

{ "integrationStyleSheets": [
    { "content": "p { font-family: sans-serif }" },
    { "uri": "http://myServer/corporate-identity.css" }
]}

User Scripts

User scripts represent additional JavaScripts. They are executed after all document JavaScript has finished processing. You can optionally run certain user scripts before any document JavaScript by specifying the beforeDocumentScripts property. This is useful for e.g. JavaScript-based shims.

User scripts can be added like this:

config.setUserScripts(
    new Resource().setContent("console.log('executed first')")
        .setBeforeDocumentScripts(true),
    new Resource().setUri("http://myServer/my.js"));

config.UserScripts = new List<Resource>
{
    new Resource()
    {
        Content = "console.log('executed first')",
        BeforeDocumentScripts = true
    },
    new Resource() { Uri = "http://myServer/my.js" }
};

config.userScripts = [
    {
        content: "console.log('executed first')",
        beforeDocumentScripts: true
    },
    { uri: "http://myServer/my.js" }
];

config.userScripts = [
    {
        content: "console.log('executed first')",
        beforeDocumentScripts: true
    },
    { uri: "http://myServer/my.js" }
];

$config["userScripts"] = array(
    array(
        "content" => "console.log('executed first')"),
        "beforeDocumentScripts" => true
    ),
    array("uri" => "http://myServer/my.js")
);

config['userScripts'] = [
    {
        'content': 'console.log("executed first")',
        'beforeDocumentScripts': True
    },
    { 'uri': 'http://myServer/my.js' }
]

config['userScripts'] = [
    {
        'content': 'console.log("executed first")',
        'beforeDocumentScripts': true
    },
    { 'uri': 'http://myServer/my.js' }
]

{ "userScripts": [
    {
        "content": "console.log('executed first')",
        "beforeDocumentScripts": true
    },
    { "uri": "http://myServer/my.js" }
]}

XSLT Style Sheets

When converting XML documents, you can add XSLT style sheets in your integration code to transform the XML into HTML. They can be added like this:

config.setXsltStyleSheets(
    new Resource().setUri("http://myServer/my.xsl"));

config.XsltStyleSheets = new List<Resource>
{
    new Resource() { Uri = "http://myServer/my.xsl" }
};

config.xsltStyleSheets = [
    { uri: "http://myServer/my.xsl" }
];

config.xsltStyleSheets = [
    { uri: "http://myServer/my.xsl" }
];

$config["xsltStyleSheets"] = array(
    array("uri" => "http://myServer/my.xsl")
);

config['xsltStyleSheets'] = [
    { 'uri': 'http://myServer/my.xsl' }
]

config['xsltStyleSheets'] = [
    { 'uri': 'http://myServer/my.xsl' }
]

{ "xsltStyleSheets": [
    { "uri": "http://myServer/my.xsl" }
]}

Color Keywords

Instead of using color functions or the hexadecimal notation a single human readable keyword can be used. For more information which keywords are supported by PDFreactor see the CSS Color Keywords table. The keywords are internally converted into the user-set color space. By default, they are converted into RGB colors.

RGB Colors

In CSS you can specify RGB Red Green Blue, additive color model, consisting of the color components red, blue and green. colors in the following ways:

• # followed by a 6 digit RGB value in hexadecimal notation, e.g. #00ff00 for perfect green. Adding two more digits defines the alpha channel, with ff being opaque.

  You can abbreviate this notation by using only 3 digits which will be expanded internally, e.g. #0f5 equals #00ff55. The same can be done with 4 digits to also define the alpha channel.

• Using the function rgb. It takes the 3 RGB component values as parameters in decimal or percent notation, e.g. rgb(0,255,0) or rgb(0%,100%,0%) for perfect green.

RGBA Colors

RGBA Red Green Blue Alpha, a color model similar to RGB, with extra information about the translucency. colors are also supported and can be specified by using the function rgba. It takes the 3 RGB component values as well as 1 alpha component value as parameters in decimal or percent notation, e.g. rgba(0,0,255,0.5) or rgba(0%,100%,0%,50%) for semi-translucent blue.

While it is currently possible to set RGBA colors on any CSS border, complex border settings (e.g. table cells borders) or border styles other than "solid" are not yet supported and may cause unexpected visual outcome.

CMYK Colors

Besides rgb and rgba PDFreactor also supports the non-standard function cmyk. It takes the 4 CMYK component values as parameters in decimal or percent notation, e.g. cmyk(0,0,1,0) or cmyk(0%,0%,100%,0%) for perfect yellow. An optional fifth parameter can be used to define the color's alpha value, e.g. cmyk(0%,0%,100%,0%,10%) would be a transparent yellow with an alpha of only 10%.

Color keywords can be converted automatically into CMYK using the configuration property colorSpaceSettings.targetColorSpace:

config.setColorSpaceSettings(new ColorSpaceSettings()
    .setTargetColorSpace(ColorSpace.CMYK);

config.ColorSpaceSettings = new ColorSpaceSettings
{
    TargetColorSpace = ColorSpace.CMYK
};

config.colorSpaceSettings = {
    targetColorSpace: PDFreactor.ColorSpace.CMYK
}

config.colorSpaceSettings = {
    targetColorSpace: PDFreactor.ColorSpace.CMYK
}

$config["colorSpaceSettings"] = array(
    "targetColorSpace" => ColorSpace::CMYK
);

config['colorSpaceSettings'] = {
    'targetColorSpace': PDFreactor.ColorSpace.CMYK
}

config['colorSpaceSettings'] = {
    targetColorSpace: PDFreactor::ColorSpace::CMYK
}

{ "colorSpaceSettings": {
    "targetColorSpace": "CMYK"
}}

CMYK colors are also supported in SVGs.

HSL Colors

HSL Hue Saturation Lightness, alternative representation of colors of the RGB color model. is another representation of the RGB color space. The hue value is in the range of 0 to 360, the saturation and lightness values range between 0 and 1. It is possible to set HSL colors using the function hsl. It takes the 3 HSL component values as parameters in decimal or percent notation, e.g. hsl(240,0,0) or hsl(66%,0%,0%) for blue. As with rgb, there is also the function hsla, though both functions allow an additional parameter for the alpha value.

Spot Colors

Spot or separation colors, e.g. Pantone colors, are special named colors for professional printing. The specific color name is passed as is to the print workflow. As they cannot be displayed on screen (or printed without the correct named color), a fallback color must be specified, e.g. a similar CMYK color. A spot color can be used via the CSS function -ro-spot and its synonym -ro-separation. The function takes two or three parameters: The spot color name, the color tint (which is optional and defaults to 1.0, which represents maximum "opacity") and the fallback color.

Spot colors are also supported in SVGs.

Color Conversion

Different colors can be converted into a common color space. See for more information.

Images

PDFreactor has support for the image formats PNG, JPEG, TIFF, BMP, GIF as wells as limited support for WebP (lossy simple VP8).

Images are embedded by PDFreactor "as-is", whenever possible, unless the properties or are used. This means that images are not modified in any way and will be embedded without any re-encoding and without any loss in quality. Possible discrepancies in perceived quality might occur depending on the PDF viewer and the zoom level.

PDFreactor supports the img element per default in HTML. For other XML languages, you can use proprietary CSS extensions to define an image element. For example, in an XML vocabulary where an image element is <image source='test.jpg'>, the corresponding CSS definition would be:

image {
    -ro-replacedelement: image;
    -ro-source: attr(source);
}

To define an element as image element, you must specify the replaced element formatter for images for this element, as displayed in the example above. Using the property and the attr function, you can select an attribute of this element. The value of this attribute must always be of the type URI Uniform Resource Identifier (https://www.w3.org/Addressing/) and is used to load the image.

config.setProcessingPreferences(
    ProcessingPreferences.SAVE_MEMORY_IMAGES);

config.ProcessingPreferences = new List<ProcessingPreferences>
{
    ProcessingPreferences.SAVE_MEMORY_IMAGES
};

$config["processingPreferences"] = 
    array(ProcessingPreferences::SAVE_MEMORY_IMAGES);

config['processingPreferences'] =
    [ PDFreactor.ProcessingPreferences.SAVE_MEMORY_IMAGES ]

config['processingPreferences'] =
    [ PDFreactor::ProcessingPreferences::SAVE_MEMORY_IMAGES ]

config.processingPreferences =
    [ PDFreactor.ProcessingPreferences.SAVE_MEMORY_IMAGES ];

config.processingPreferences =
    [ PDFreactor.ProcessingPreferences.SAVE_MEMORY_IMAGES ];

{ "processingPreferences": [ "SAVE_MEMORY_IMAGES" ] }

SVG

PDFreactor supports the following SVG Scalable Vector Graphics (https://www.w3.org/Graphics/SVG/) types: SVG and SVGZ. PDFreactor automatically converts SVG documents referenced via the img element. Example:

<img src="diagram.svg" />

Alternatively, you can embed SVG directly into your documents:

a circle:<br/>
<svg width="100" height="100">
    <circle cx="50" cy="50" r="45" fill="yellow" stroke="black" />
</svg>
<br/>sometext.......

<svg:svg xmlns:svg="http://www.w3.org/2000/svg" width="100" height="100">
    <svg:circle cx="50" cy="50" r="45" fill="yellow" stroke="black" />
</svg:svg>

stroke="cmyk(0.0, 0.0, 0.0, 1.0)"

MathML

To display MathMLMathematical Markup Language (https://www.w3.org/Math/) in documents we recommend using the JavaScript library MathJaxMathJax (https://www.mathjax.org/ & https://github.com/mathjax/MathJax/) licensed under the Apache License 2.0 using SVG output.

<script type="text/x-mathjax-config">
    MathJax.Hub.Config({
        showMathMenu: false
                 jax: ["input/MathML", "output/SVG"],
          extensions: ["mml2jax.js"],
              MathML: { extensions: ["content-mathml.js"] },
                 SVG: { blacker: 0 }
    });
</script>
<script src="url/to/MathJax.js></script>

import { loadMathJax } from 'url/to/awesomizr.js';
loadMathJax('url/to/MathJax.js');

To use MathJax without modifying the input documents you can add it as a user script (see ), in which case using Awesomizr to load it is recommended.

Barcodes

PDFreactor supports displaying numerous linear and 2D barcode symbologies using the following style:

.barcode {
    -ro-replacedelement: barcode;
}

The resulting replaced element can be customized by applying various CSS properties.

The most important one is -ro-barcode-type, which can be used to select a specific type (and subtype) of barcode to be rendered. For some types, the last argument of the property is also used to configure a unique characteristic of the barcode (refer to the appendix for more information).

Defining the Content

There are multiple ways to define the content of the barcode. To define it directly, you can use the -ro-barcode-content property:

.barcode {
    -ro-replacedelement: barcode;
    -ro-barcode-type: upc-e;
    -ro-barcode-content: "123456";
}

As MaxiCodes require a primary string in mode 2 or 3, the last argument of -ro-barcode-type is used to add it.

.barcode {
    -ro-replacedelement: barcode;
    -ro-barcode-type: maxicode mode-3 "999999999840012";
    -ro-barcode-content: "1234567894561230";
}

If -ro-barcode-content is not set, PDFreactor will try to use the value of the element's href attribute:

HTML:

<a id="qrcode" href="https://www.pdfreactor.com/"></a>

CSS:

#qrcode {
    -ro-replacedelement: barcode;
    -ro-barcode-type: qrcode;
    -ro-barcode-ecc-level: H;
    -ro-barcode-size: 2;
}

If both -ro-barcode-content and the href attribute are empty, PDFreactor will use the text content of the element. That content is always trimmed, i.e. whitespace characters at its beginning and end are removed. By default other sequences of whitespace characters are collapsed to single spaces. Collapsing can be disabled by changing the value of white-space from normal to pre.

Automatically resolving relative URLs

If a relative URL is set as the barcode's content using the url function, or if it is retrieved from the href attribute, PDFreactor will automatically try to resolve it according to the document's baseUrl.

HTML:

<a id="gridmatrix" href="#Barcodes"></a>

CSS:

#gridmatrix {
    -ro-replacedelement: barcode;
    -ro-barcode-type: grid-matrix;
}

If links are enabled, PDFreactor will automatically check whether the content of the barcode is a valid URL and add the respective link.

Adjusting human readable text

For all barcode types that possess human readable text, some additional changes can be applied. The used font can be customized using the -ro-barcode-font-size and -ro-barcode-font-family properties. The position and alignment of the human readable text can be changed using the -ro-barcode-human-readable-position property, which can also be used to remove it entirely. The -ro-barcode-letter-spacing property can be used to adjust the human readable text's letter-spacing. If the barcode type allows for affixes to be added to the human readable text, they can be configured using the -ro-barcode-human-readable-affix property. A detailed list on which barcode types possess affixes can be found in the appendix.

HTML:

<a id="code-128-no-human-readable" href="#Barcodes"></a>

CSS:

#code-128-no-human-readable {
    -ro-replacedelement: barcode;
    -ro-barcode-type: code128;
    -ro-barcode-human-readable-position: none;
    -ro-barcode-content: "123456";
}

Object and Embed

PDFreactor supports the object and embed elements of HTML. You can use either element or a combination of both to embed any type of data such as for example a flash animation. The most simple code to do so is:

<embed src="myflash.swf" width="256" height="256"
       type="application/x-shockwave-flash"/>

Form Controls

PDFreactor supports HTML form elements. These form controls are non-interactive by default (but can be made interactive). Their visual appearance may deviate from common web browsers to provide a look and feel that is generally more appropriate for print media.

The default appearance of form elements is also not tied to the operating system like in browsers. In fact, PDFreactor only provides a simple, printer-friendly appearance that is fully stylable via CSS. This means that CSS properties such as color and padding also influence form controls like checkboxes and radio buttons whereas these styles have usually no effect in browsers unless these form elements are styled with appearance: none.

input[type="checkbox"],
input[type="radio"] {
    background: white !important;
    border: 1pt solid lightgray !important;
    color: white !important;
    padding: 0 !important;
}
input[type="checkbox"]:checked,
input[type="radio"]:checked {
    background: cornflowerblue !important;
    border-color: cornflowerblue !important;
}

iframes

An iframe allows another document, for example content from other pages, to be embedded inside an existing one.

The second option is useful if the inner document is very short and simple. When using the srcdoc attribute, its value is set to be the inner document's source code.

<iframe src="https://www.pdfreactor.com" width="600" height="400">
</iframe>

<iframe srcdoc="<p>Hello World</p>">
    <b>This is fallback text in case the user-agent does not support
        iframes.</b>
</iframe>
        

Furthermore, the borders of the iframe are removed and most importantly all styles from the outer document are inherited by the inner document.

When generating the PDF, the headings and other bookmark styles inside the iframe are passed through, so they can be found in the bookmark list.

The seamless attribute is a boolean attribute, which means that if it is true it exists and false otherwise. The only valid values of seamless are an empty string or "seamless". The attribute can also be used without any value:

<iframe src="https://www.pdfreactor.com" width="600" height="400"
            seamless>
</iframe>

iframe {
    border: none;
    padding: 0px;
    margin: 0px;
}

By default, if seamless is false neither style sheets nor inline styles are passed down to the iframe's document. However, by using the property , this behavior can be customized.

When generating a PDF with the bookmarks feature enabled, the headings in the document are added as bookmarks to quickly navigate the document.

Using the property it is possible to enable or disable this feature for iframes, thus allowing the headings of the inner document to be added to the bookmarks list or not. The property can be either set to true or false. If the iframe is seamless, it is set to true by default.

<iframe src="https://www.pdfreactor.com" width="600" height="400"
    seamless="seamless" style="-ro-passdown-styles:stylesheets-only;
    -ro-bookmarks-enabled:false;">
</iframe>

Canvas Element

PDFreactor has built-in support for the canvas element of HTML5. The canvas element is a dynamic image for rendering graphics primitives on the fly. In contrast to other replaced elements the content of the canvas element must be generated dynamically via , instead of referencing an external resource that contains the content to be displayed (as is the case for example for images).

Below is a simple code fragment which renders shadowed text into a canvas element:

<head>
    <script type="text/javascript">
        function draw() {
            let ctx = document.getElementById("canvas").getContext('2d');
            ctx.font = "50px 'sans-serif'";
            ctx.shadowBlur = 5;
            ctx.shadowColor = "#aaa";
            ctx.shadowOffsetX = 2;
            ctx.shadowOffsetY = 2;
            ctx.fillStyle = "black";
            ctx.fillText("PDFreactor",0,50);
        }
    </script>
</head>
...
<body onload="draw();">
    <canvas id="canvas" width="400" height="300">
        Canvas element is not supported.
    </canvas>
</body>

Shadows cannot be convert to PDF objects. So those are added as images. This does not affect other objects in the canvas.

Accessing ImageData of a canvas or setting a non-default composite causes that canvas to be rasterized entirely.

This behavior can be configured using CSS:

The style -ro-rasterization: avoid disables functionality that causes the rasterization of the canvas.

The style -ro-rasterization: always forces the canvas to be rasterized in any case.

The property configures the resolution at which the canvas or shadows are rasterized. The default value is 2, meaning twice the default CSS resolution of 96dpi. Accepted values are 1 to 4. Higher resolution factors increase the quality of the image, but also increase the conversion time and the size of the output documents. This does not affect canvas objects that are not rasterized.

PDF Pages as Images

PDFreactor can losslessly embed pages from other PDFs as images in the document to be converted to PDF or draw them into image output. To use a PDF as an image in a document, simply use the img element, like you would for any other image. Example:

<img src="https://resources.myserver.com/report.pdf" />

In the example above, the PDF image will always display the first page of the PDF. You can select which page should be displayed using the CSS property -ro-source-page. The example below shows how to display page 5 of the PDF:

<img src="https://resources.myserver.com/report.pdf" style="-ro-source-page: 5" />

By default the media box, i.e. the entire sheet, of the PDF page is visible and used for sizing. This can be reduced to any other PDF page box like "crop" or "trim" via the property -ro-source-area. The example below shows how to display only the crop box of the PDF page:

<img src="https://resources.myserver.com/report.pdf" style="-ro-source-area: 'crop'" />

PDF images expose the page count of their source document to JavaScript via the proprietary property roPageCount of the img HTML element. If the object is not a PDF image roPageCount will return 0. In the following example, let's assume we have a PDF image with the id "pdfimage":

let reportPdf = document.getElementById("pdfimage");
let pageCount = reportPdf.roPageCount;

Aside from using image elements, PDFs can be used in most places other images are supported. For example, you can embed PDFs as background images. With the exception of being able to access the page count using JavaScript, the behavior described above also applies to them:

.pdfBackground-2 {
    background-image: url("https://resources.myserver.com/backgrounds.pdf");

    /* Apply styles like -ro-source-page or -ro-source-area to the same element as background image. */
    -ro-source-page: 2;
}

Filters and Shadows

Certain effects, like blurring, are not natively supported by the PDF format. In such cases, PDFreactor has to generate an image of the corresponding element, with the effects already applied. The image can always be displayed in the PDF and if necessary an invisible text overlay above the image ensures, that the text inside the element can still be selected, copied and is accessible, e.g. to screen readers.

The CSS properties that require element rasterization are:

• box-shadow (only the shadow itself is rastered. The content of the element can be rendered as usual).

• filter

• text-shadow

The resolution of the resulting image can be customized via the -ro-rasterization-supersampling property. The default value is 2, meaning 192dpi, as a compromise between quality, performance and size.

Please note that increasing the resolution or applying shadows and filters on large or many elements will not only increase the size of the converted PDF but may also slow down PDF readers.

As a safeguard against memory and performance issues, the maximum size of a single rasterized image can be limited. By default an image will be rasterized to have less than 2 megapixels. This is still large enough to cover an A4 page-sized image with the default supersampling. The CSS property allows to customize or disable that limit.

Limitations of Browser-Like Behavior

JavaScript processing during PDF conversion works like it does in a browser, with some exceptions:

• The delays of setTimeout or setInterval are applied only to the virtual time of JavaScript processing and do not actually slow down the conversion.

• Alerts and other dialogs are logged and do not stop script processing.

• There are no browser-like security measures based on the origins of URLs ("cross-site scripting"). However, the mechanism of PDFreactor is applied to all connections caused by JavaScript. This has the advantage that XMLHttpRequest and Fetch can access file-URLs, when those are allowed. Module "import" statements also can access any URL, incl. file, that is not prohibited.

JavasScript processing is subject to a few other limitations that will be eliminated in future versions of PDFreactor:

• DOM access to elements inside embedded SVGs may be subject to minor limitations.

• Reading from and manipulating form DOM elements via their specific JS attributes and methods is not fully supported.

• Coordinates (e.g. retrieved via getDOMRects) are relative to their pages, which might lead to unexpected results in some situations.

• Redirects (e.g. changing window.location) are not possible.

• Scripting support in iframes is limited.

• When a module is imported from an absolute URL the modules it imports in-turn, directly or transitively, must be specified as relative paths or absoltue URLs. Absolute paths will errouniously be resolved against the origin of the root document.

• Support for import maps is limited to the "imports" module specifier map.

JavaScript Engines

PDFreactor uses a JavaScript implementation based on the JavaScript engine Oracle GraalJS. Previous versions used Mozilla Rhino as JavaScript engine and that engine can still be enabled via a setting. However, we recommend to only use it as a temporary solution for the rare cases when it supports scripts that GraalJS does not yet handle correctly. Please note that Rhino only offers partial support for ECMAScript 2015 (ES6) while GraalJS fully supports ECMAScript 2023 syntax.

config.setJavaScriptSettings(new JavaScriptSettings()
    .setJavaScriptEngine(JavaScriptEngine.RHINO));

config.JavaScriptSettings = new JavaScriptSettings
{
    JavaScriptEngine = JavaScriptEngine.RHINO
};

config.javaScriptSettings = {
    javaScriptEngine: PDFreactor.JavaScriptEngine.RHINO
};

config.javaScriptSettings = {
    javaScriptEngine: PDFreactor.JavaScriptEngine.RHINO
};

$config["javaScriptSettings"] = array(
    "javaScriptEngine" => JavaScriptEngine::RHINO
);

config['javaScriptSettings'] = {
    'javaScriptEngine': PDFreactor.JavaScriptEngine.RHINO
}

config['javaScriptSettings'] = {
    'javaScriptEngine': PDFreactor::JavaScriptEngine::RHINO
}

{ "javaScriptSettings": {
    "javaScriptEngine": "RHINO"
}}

Third-Party JavaScript Libraries and Frameworks

PDFreactor supports various third-party JavaScript libraries and frameworks. See for details.

Proprietary Access to Layout Information

PDFreactor allows JavaScript access to some layout information via the proprietary object ro.layout.

let pageDesc = ro.layout.getPageDescription(1);

let element = document.querySelector("#myElem");
let boxDescriptions = ro.layout.getBoxDescriptions(element);

if (boxDescriptions.length > 0) {
    let boxDescription = boxDescriptions[0];
}

let lineDescriptions = boxDescription.lineDescriptions;

let marginRect = boxDescription.getMarginRect("cm");

PDF Output Options

It is possible to specify portions of the PDFreactor configuration in document JavaScript at runtime during the conversion. This can be useful if you want to create PDF attachments dynamically, specify PDF-specific settings like encryption on the fly, change the page order according to content-specific criteria, etc.

You can access these PDF output options via the proprietary object ro.pdf. For a full list of supported properties refer to . The default value of these properties is taken from their respective configuration setting from your PDFreactor configuration. For example, if you have specified the author to be "John Smith" in your configuration, the value of the ro.pdf.author property will also be "John Smith" initially and can be changed as desired.

ro.pdf.attachments.push({
    name: "log.txt",
    data: "My log text.",
    description: "A JavaScript log"
});

graphCanvas.toBlob((graphBlob) => {
    ro.pdf.attachments.push({
        name: "graph1975.png",
        data: graphBlob,
        description: "Statistics of 1975"
    });
});

ro.pdf.pageOrder = "1..2,4..-1";

config.setAuthor("Brian Greene");
config.setTitle("The Elegant Universe");

config.Author = "Brian Greene";
config.Title = "The Elegant Universe";

$config["author"] = "Brian Greene";
$config["title"] = "The Elegant Universe";

config['author'] = "Brian Greene"
config['title'] = "The Elegant Universe"

config['author'] = "Brian Greene"
config['title'] = "The Elegant Universe"

config.author = "Brian Greene";
config.title = "The Elegant Universe";

config.author = "Brian Greene";
config.title = "The Elegant Universe";

{ "author": "Brian Greene", "title": "The Elegant Universe" }

ro.pdf.author = "Stephen Hawking";
ro.pdf.title = "The Universe in a Nutshell";

Exporting Data From JavaScript

Sometimes it can be desirable to make data from JavaScript available to the PDFreactor integration for further processing after the conversion has finished. You can export data from document JavaScript by setting the JavaScript property ro.exports. The exported data can then be accessed in the API via the javaScriptExports property of the Result object of the conversion.

You can export any data type with ro.exports. However, since the property javaScriptExports returns a string, the data will be converted internally. If the data type is not a string, PDFreactor will try to convert it to JSON. This means that you can conveniently export JavaScript objects or arrays, and then parse the data back from JSON. If the data can't be converted, a generic string representation of it is used or null if none is available.

ro.exports = {
    message: "my exported data",
    content: [ 1, 2, 3 ]
};

{"message":"my exported data","content":[1,2,3]}

String javaScriptExports = result.getJavaScriptExports();

String javaScriptExports = result.JavaScriptExports;

$javaScriptExports = $result->javaScriptExports;

javaScriptExports = result['javaScriptExports'];

javaScriptExports = result["javaScriptExports"]

const javaScriptExports = result.javaScriptExports;

const javaScriptExports = result.javaScriptExports;

$.javaScriptExports

Timeouts and Limits

For various reasons scripts may run unnecessarily long or even endlessly. PDFreactor imposes various limits to avoid long conversion times.

Most limits are intended for scripts that would run for an excessive amount of time because of the script expecting an interactive browser environment. They end JavaScript processing but let the conversion continue on.

However, some limits target erroneous or malicious scripts as well as complex scripts that end up running endlessly due to missing functionality. Reaching one of those terminates the conversion with a matching exception.

config.setJavaScriptSettings(new JavaScriptSettings()
    .setTimeout(20));

config.JavaScriptSettings = new JavaScriptSettings
{
    Timeout = 20
};

config.javaScriptSettings = {
    timeout: 20
};

config.javaScriptSettings = {
    timeout: 20
};

$config["javaScriptSettings"] = array(
    "timeout" => 20
);

config['javaScriptSettings'] = {
    'timeout': 20
}

config['javaScriptSettings'] = {
    'timeout': 20
}

{ "javaScriptSettings": {
    "timeout": 20
}}

awesomizr.js

The JavaScript library awesomizr.js is a collection of helpful functions for the use with PDFreactor. You have to import the JavaScript and in some cases the corresponding CSS. Both the script and the css files are located in the PDFreactor/samples directory.

You can add the library by using the PDFreactor configuration property userScripts. To add the respective CSS, use the property userStyleSheets:

config
    .setUserStyleSheets(new Resource()
        .setUri("awesomizr.css"))
    .setUserScripts(
        new Resource()
            .setContent("import * as Awesomizr from './awesomizr.js'; Awesomizr.createTableOfContents();")
            .setSubtype(ResourceSubtype.JAVASCRIPT_MODULE));

config.UserStyleSheets = new List<Resource>
{
    new Resource
    {
        Uri = "awesomizr.css"
    }
};
config.UserScripts = new List<Resource>
{
    new Resource
    {
        Content = "import * as Awesomizr from './awesomizr.js'; Awesomizr.createTableOfContents();",
        Subtype = PDFreactor.ResourceSubtype.JAVASCRIPT_MODULE
    }
};

config.userStyleSheets = [{
    uri: "awesomizr.css"
}];
config.userScripts = [{
    content: "import * as Awesomizr from './awesomizr.js'; Awesomizr.createTableOfContents();",
    subtype: PDFreactor.ResourceSubtype.JAVASCRIPT_MODULE
}];

config.userStyleSheets = [{
    uri: "awesomizr.css"
}];
config.userScripts = [{
    content: "import * as Awesomizr from './awesomizr.js'; Awesomizr.createTableOfContents();",
    subtype: PDFreactor.ResourceSubtype.JAVASCRIPT_MODULE
}];

$config["userStyleSheets"] = array(
    array(
        "uri" => "awesomizr.css"
    )
);
$config["userScripts"] = array(
    array(
        "content" => "import * as Awesomizr from './awesomizr.js'; Awesomizr.createTableOfContents();",
        "subtype" => ResourceSubtype::JAVASCRIPT_MODULE
    )
);

config['userStyleSheets'] = [{
    'uri': 'awesomizr.css'
}]
config['userScripts] = [{
    'content': 'import * as Awesomizr from "./awesomizr.js"; Awesomizr.createTableOfContents();',
    'subtype': PDFreactor.ResourceSubtype.JAVASCRIPT_MODULE
}]

config['userStyleSheets'] = [{
    'uri': 'awesomizr.css'
}]
config['userScripts] = [{
    'content': 'import * as Awesomizr from "./awesomizr.js"; Awesomizr.createTableOfContents();',
    'subtype': PDFreactor::ResourceSubtype::JAVASCRIPT_MODULE
}]

{
    "userStyleSheets": [{
        "uri": "awesomizr.css"
    }],
    "userScripts": [{
        "content": "import * as Awesomizr from './awesomizr.js'; Awesomizr.createTableOfContents();",
        "subtype": "JAVASCRIPT_MODULE"
    }]
}

The capabilities of awesomizr.js include:

• Rotating table headers to reduce the table header width

• Fitting wide tables onto narrow pages

• Adaptive Page Break Insertion

• Creating a Table of Contents

Bookmarks

PDFreactor adds bookmarks to your document automatically. This can be disabled by using the disableBookmarks configuration property like this:

config.setDisableBookmarks(true);

config.DisableBookmarks = true;

$config["disableBookmarks"] = true;

config['disableBookmarks'] = True

config['disableBookmarks'] = true

config.disableBookmarks = true;

config.disableBookmarks = true;

{ "disableBookmarks": true }

When the default HTML mode is enabled, some bookmark levels are applied by default, e.g. the following ones for heading elements:

h1 { bookmark-level: 1;}
h2 { bookmark-level: 2;}
h3 { bookmark-level: 3;}
h4 { bookmark-level: 4;}
h5 { bookmark-level: 5;}
h6 { bookmark-level: 6;}

Using the bookmark-level style you can create bookmarks which link to arbitrary XML elements in your PDF files.

element { bookmark-level: 1; }

The property bookmark-state defines whether the entry is initially open, showing its descendants in the bookmark view of the PDF viewer. With the property bookmark-label it is possible to define the bookmark title. By default, the element's text content is used.

How the coordinate to scroll to is determined can be changed via the property , e.g. the scroll target can be offset by 1cm or the page the element is on can be used instead of the element itself.

Links

PDFreactor adds links to your documents by default. This can be disabled by using the disableLinks configuration property like this:

config.setDisableLinks(true);

config.DisableLinks = true;

$config["disableLinks"] = true;

config['disableLinks'] = True

config['disableLinks'] = true

config.disableLinks = true;

config.disableLinks = true;

{ "disableLinks": true }

For HTML documents the following link styles are applied by default, enabling external and internal links:

a[href] { -ro-link:   attr(href); }
a[name] { -ro-anchor: attr(name); }
[id]    { -ro-anchor: attr(id);   }

Using the styles and arbitrary elements can be defined to be links or anchors.

linkElement[linkAttribute] { -ro-link: attr(linkAttribute); }
anchorElement[anchorAttribute] { -ro-anchor: attr(anchorAttribute); }

Please see for a way to embed target files into the output PDF instead of linking to them.

Metadata

The title of a generated PDF document, as well as the additional metadata author, subject and keywords, can be specified in multiple ways:

By default the <title> tag as well as various <meta> tags are read.

The metadata can also be read from other elements using the properties , , and .

/* Disable setting title from title or meta tags */
head * {
    -ro-title: none;
}
/* Set title from first heading */
body > h1:first-of-type {
    -ro-title: content();
}

The metadata of the document can be overridden from the API. The following metadata can be directly set by PDFreactor:

• author – The author of the document

• title – The document's title

• subject – The subject of the document

• creator – The content creator

• keywords – Usually a comma-separated list of keywords for search engines

config
    setAuthor("John Doe")
    setTitle("Architecture of the World Wide Web, Volume One")
    setSubject("Architecture of the world wide web")
    setCreator("John's DoeNuts, Inc.")
    setKeywords("w3c, www");

config.Author = "John Doe";
config.Title = "Architecture of the World Wide Web, Volume One";
config.Subject = "Architecture of the world wide web";
config.Creator = "John's DoeNuts, Inc.";
config.Keywords = "w3c, www";

$config["author"] = "John Doe";
$config["title"] = "Architecture of the World Wide Web, Volume One";
$config["subject"] = "Architecture of the world wide web";
$config["creator"] = "John's DoeNuts, Inc.";
$config["keywords"] = "w3c, www";

config['author'] = 'John Doe'
config['title'] = 'Architecture of the World Wide Web, Volume One'
config['subject'] = 'Architecture of the world wide web'
config['creator'] = 'John's DoeNuts, Inc.'
config['keywords'] = 'w3c, www'

config['author'] = 'John Doe'
config['title'] = 'Architecture of the World Wide Web, Volume One'
config['subject'] = 'Architecture of the world wide web'
config['creator'] = 'John's DoeNuts, Inc.'
config['keywords'] = 'w3c, www'

config.author = "John Doe";
config.title = "Architecture of the World Wide Web, Volume One";
config.subject = "Architecture of the world wide web";
config.creator = "John's DoeNuts, Inc.";
config.keywords = "w3c, www";

config.author = "John Doe";
config.title = "Architecture of the World Wide Web, Volume One";
config.subject = "Architecture of the world wide web";
config.creator = "John's DoeNuts, Inc.";
config.keywords = "w3c, www";

{ "author": "John Doe",
  "title": "Architecture of the World Wide Web, Volume One",
  "subject": "Architecture of the world wide web",
  "creator": "John's DoeNuts, Inc.",
  "keywords": "w3c, www" }

The code above creates metadata as shown in the screenshot below:

config.setCustomDocumentProperties(
    new KeyValuePair("feedback address", "peter@miller.com"));

config.CustomDocumentProperties = new List<KeyValuePair>
{
    new KeyValuePair("feedback address", "peter@miller.com")
};

$config["customDocumentProperties"] = array(
    array(
        "key" => "feedback address",
        "value" => "peter@miller.com"
    )
);

config['customDocumentProperties'] = [
    { 'key': "feedback address", 'value': "peter@miller.com" }
]

config['customDocumentProperties'] = [
    { key: "feedback address", value: "peter@miller.com" }
]

config.customDocumentProperties = [
    { key: "feedback address", value: "peter@miller.com" }
];

config.customDocumentProperties = [
    { key: "feedback address", value: "peter@miller.com" }
];

{ "customDocumentProperties": [
    { "key": "feedback address", "value": "peter@miller.com" }
]}

Interactive PDF Forms

HTML forms are rendered automatically by PDFreactor. In addition, you can also convert HTML forms to fully functional interactive PDF forms (sometimes referred to as AcroForms) using the proprietary CSS property . This property must be specified for the forms you wish to convert to an interactive PDF form.

Example form:

<form id="credentials">
    First Name: <input type="text" value="firstname" />
    Last Name: <input type="text" value="lastname" />
    <input type="submit" />
</form>

To convert the form with the ID "credentials" to an AcroForm, you can use this style declaration:

#credentials, #credentials > input { -ro-pdf-format: pdf; }

form, form input { -ro-pdf-format: pdf; }

Tagged PDF

Tagged PDF files contain information about the structure of the document. The information about the structure is transported via so-called "PDF tags". Tagging a PDF makes it accessible to assistive technology like screen readers. Please see the chapter for further information. Furthermore, depending on the application, it may improve the results of copy and paste or allow more advanced processing of the PDF.

Using the addTags configuration property, you can add PDF tags to the PDF documents generated with PDFreactor. If you are generating a PDF from HTML input, the HTML elements and the resulting layout are automatically mapped to the appropriate PDF tag structures, so all you have to do is set the following configuration property to enable this feature:

config.setAddTags(true);

config.AddTags = true;

$config["addTags"] = true;

config['addTags'] = True

config['addTags'] = true

config.addTags = true;

config.addTags = true;

{ "addTags": true }

PDF/A Conformance

PDFreactor supports the creation of PDF/A-1a or PDF/A-3a conformant files, as well as other PDF/A sub-formats, which, however, will not be covered in detail.

PDF/A is a family of ISO standards ("ISO 19005") for long-term archiving of documents. The goal of these standards is to ensure the reproduction of the visual appearance as well as the inclusion of the document's structure. All information necessary for displaying the document in the same way every time is embedded in the file. Dependencies on external resources are not permitted. PDF/A-1a and PDF/A-3a also require the output PDF documents to be tagged, providing accessible documents. PDFreactor will automatically ensure the requirements are met as far as possible.

Many companies and government organizations worldwide require PDF/A compliant documents.

PDF/A-1a is the strictest PDF/A standard while the newer PDF/A-3a is more lenient, e.g. allowing transparency and attachments.

PDF/A imposes the following restrictions, which PDFreactor automatically enforces (overriding configuration settings), so no manual intervention is required unless noted otherwise:

• All used fonts are embedded.

• All images are embedded.

• Multi-media content is forbidden.

• PDF Script is prohibited. (Does not affect JavaScript in the source HTML document)

• Encryption is prohibited.

• Metadata included in the PDF is required to be standard-based XMP.

• Colors are specified in a device-independent manner. (see below)

• The PDF must be tagged. (PDF/A-1a, PDF/A-2a and PDF/A-3a only)

• Attachments are prohibited. (PDF/A-1 only)

• Transparency is prohibited (PDF/A-1 only), see image alpha channels in PDF/A-1.

PDF/A documents must use either RGB or CMYK colors exclusively (color keywords and gray colors will be converted appropriately). By default RGB colors are expected. Using CMYK requires an output intent including an ICC profile. (It is also possible to specify an RGB profile to replace the default sRGB.) Please see .

To create a PDF/A conformant document, the configuration property conformance is used in the PDFreactor integration, e.g.:

config.setConformance(Conformance.PDFA3A);

config.Conformance = Conformance.PDFA3A;

$config["conformance"] = Conformance::PDFA3A;

config['conformance'] = PDFreactor.Conformance.PDFA3A

config['conformance'] = PDFreactor::Conformance::PDFA3A

config.conformance = PDFreactor.Conformance.PDFA3A;

config.conformance = PDFreactor.Conformance.PDFA3A;

{ "conformance": "PDFA3A" }

The supported PDF/A conformance levels are PDF/A-1a, PDF/A-1b, PDF/A-2a, PDF/A-2b, PDF/A-2u, PDF/A-3a, PDF/A-3b and PDF/A-3u.

config.setIgnoreAlpha(true);

config.IgnoreAlpha = true;

$config["ignoreAlpha"] = true;

config['ignoreAlpha'] = True

config['ignoreAlpha'] = true

config.ignoreAlpha = true;

config.ignoreAlpha = true;

{ "ignoreAlpha": true }

config.setValidateConformance(true);

config.ValidateConformance = true;

$config["validateConformance"] = true;

config['validateConformance'] = True

config['validateConformance'] = true

config.validateConformance = true;

config.validateConformance = true;

{ "validateConformance": true }

config.setConformance(Conformance.PDFA3A_PDFUA);

config.Conformance = Conformance.PDFA3A_PDFUA;

$config["conformance"] = Conformance::PDFA3A_PDFUA;

config['conformance'] = PDFreactor.Conformance.PDFA3A_PDFUA

config['conformance'] = PDFreactor::Conformance::PDFA3A_PDFUA

config.conformance = PDFreactor.Conformance.PDFA3A_PDFUA;

config.conformance = PDFreactor.Conformance.PDFA3A_PDFUA;

{ "conformance": "PDFA3A_PDFUA" }

PDF/UA Conformance

PDF/UA is a standard for accessible PDF documents, which has been adopted as a recommendation or requirement by many organizations worldwide.

It primarily defines correct PDF tagging. The only other restriction that may require manual intervention is that the document must have a title. (If the title is not specified in the input document, it can be set via the configuration property title.)

When PDF/UA conformance is enabled PDF tagging is automatically enaled as well. Please see the chapter for further information.

To create a PDF/UA conformant document, the configuration property conformance can be used in the PDFreactor integration, e.g.:

config.setConformance(Conformance.PDFUA);

config.Conformance = Conformance.PDFUA;

$config["conformance"] = Conformance::PDFUA;

config['conformance'] = PDFreactor.Conformance.PDFUA

config['conformance'] = PDFreactor::Conformance::PDFUA

config.conformance = PDFreactor.Conformance.PDFUA;

config.conformance = PDFreactor.Conformance.PDFUA;

{ "conformance": "PDFUA" }

config.setConformance(Conformance.PDFA3A_PDFUA);

config.Conformance = Conformance.PDFA3A_PDFUA;

$config["conformance"] = Conformance::PDFA3A_PDFUA;

config['conformance'] = PDFreactor.Conformance.PDFA3A_PDFUA

config['conformance'] = PDFreactor::Conformance::PDFA3A_PDFUA

config.conformance = PDFreactor.Conformance.PDFA3A_PDFUA;

config.conformance = PDFreactor.Conformance.PDFA3A_PDFUA;

{ "conformance": "PDFA3A_PDFUA" }

PDF/X Conformance

PDFreactor supports the creation of PDF/X conformant files, specifically PDF/X-1a:2001, PDF/X-3:2002, PDF/X-1a:2003, PDF/X-3:2003, PDF/X-4 and PDF/X-4p. PDF/X restrictions and requirements are enforced as far as possible, which may cause configuration settings to be overridden or conversions to fail with an error message describing non-compliant content or settings that have to be resolved manually. The restrictions and requirements of PDF/X include:

• All Fonts must be embedded.

• Multimedia content and non-printable annotations are prohibited.

• Encryption is prohibited.

• No scripts may be embedded. (This does not affect JavaScript in the input document.)

• Transparency is prohibited (except in PDF/X-4), see image alpha channels in PDF/A-1.

• Colors must be specified as CMYK, gray, keywords or spot. (PDF/X-3 relaxes this restriction to allow RGB. However, this requires ICC profile based conversion, which not every print workflow can handle.)

• An output intent is required, consisting of an output condition identifier string and an ICC profile. (Depending on the exact conformance and target environment it may be legal or required to omit the ICC profile, as long as the identifier is known to the target environment. Constants for the default profiles of Adobe Acrobat Pro DC are available for usage with PDF/X-4p. Please note that the availability of these default profiles may vary between different versions of Acrobat Pro.) Please see .

• The title metadata is required. Usually, it is set by the document's title element, but it can also be set by the CSS property -ro-title. The third option is to set it via the configuration property title. Please see .

To create a PDF/X conformant document, the configuration property conformance can be used in the PDFreactor integration, e.g.:

config.setConformance(Conformance.PDFX4);

config.Conformance = Conformance.PDFX4;

$config["conformance"] = Conformance::PDFX4;

config['conformance'] = PDFreactor.Conformance.PDFX4

config['conformance'] = PDFreactor::Conformance::PDFX4

config.conformance = PDFreactor.Conformance.PDFX4;

config.conformance = PDFreactor.Conformance.PDFX4;

{ "conformance": "PDFX4" }

ICC Profiles and Output Intents

PDFreactor allows you to set the output intent of the PDF document, consisting of an identifier and an ICC profile. This is required for certain PDF/A and PDF/X conformance modes, with the ICC profile being optional in some cases. The example below demonstrates how to use the configuration property outputIntent:

config.setOutputIntent(new OutputIntent()
    .setIdentifier("ICC profile identifier")

    // Use this if you are loading the ICC profile via URL (ignored if data is set)
    .setUrl("URL/to/ICC/profile")

    // Use this if you want to specify the ICC profile's binary data
    .setData(iccProfileByteArray)
);

config.OutputIntent = new OutputIntent
{
    Identifier = "ICC profile identifier",

    // Use this if you are loading the ICC profile via URL (ignored if data is set)
    Url = "URL/to/ICC/profile",

    // Use this if you want to specify the ICC profile's binary data
    Data = iccProfileByteArray
};

config.outputIntent = {
    identifier: "ICC profile identifier",

    // Use this if you are loading the ICC profile via URL (ignored if data is set)
    url: "URL/to/ICC/profile",

    // Use this if you want to specify the ICC profile's binary data as base64 string
    data: iccProfileBase64
};

config.outputIntent = {
    identifier: "ICC profile identifier",

    // Use this if you are loading the ICC profile via URL (ignored if data is set)
    url: "URL/to/ICC/profile",

    // Use this if you want to specify the ICC profile's binary data as base64 string
    data: iccProfileBase64
};

$config["outputIntent"] = array(
    "identifier" => "ICC profile identifier",

    // Use this if you are loading the ICC profile via URL (ignored if data is set)
    "url" => "URL/to/ICC/profile",

    // Use this if you want to specify the ICC profile's binary data as base64 string
    "data" => iccProfileBase64
);

config['outputIntent'] = {
    'identifier': "ICC profile identifier",

    # Use this if you are loading the ICC profile via URL (ignored if data is set)
    'url': "URL/to/ICC/profile",

    # Use this if you want to specify the ICC profile's binary data as base64 string
    'data': iccProfileBase64
}

config['outputIntent'] = {
    identifier: "ICC profile identifier",

    # Use this if you are loading the ICC profile via URL (ignored if data is set)
    url: "URL/to/ICC/profile",

    # Use this if you want to specify the ICC profile's binary data as base64 string
    data: iccProfileBase64
}

{ "outputIntent": {
    "identifier": "ICC profile identifier",
    "url": "URL/to/ICC/profile",
    "data": iccProfileBase64
}}

The property identifier sets a string identifying the intended output device or production condition in human- or machine-readable form. The property url points to an ICC profile file and the property data sets the binary data of such a profile, the latter having priority.

The color space of the output intent profile overrides the target color space.

Color Space Conversion

In cases when output PDF documents must consist only of colors and images of a certain color space, but not all input documents and resources match that, you can enable color space conversion. For example, you can convert all CSS colors and images to CMYK with a specified ICC profile matching the output intent of a PDF/A or a PDF/X for printing:

// The required output intent
config.setOutputIntent(new OutputIntent()
    .setIdentifier("ICC profile identifier")
    .setUrl("URL/to/ICC/profile"));
// Color space conversion settings
config.setColorSpaceSettings(new ColorSpaceSettings()
    // The same profile as the output intent, required for accurate conversion to CMYK
    .setCmykIccProfile(new Resource().setUri("URL/to/ICC/profile"))
    // Not necessary to set in this case (overridden by output intent), but recommended
    .setTargetColorSpace(ColorSpace.CMYK)
    // Enable conversion of RGB colors and images to CMYK
    .setConversionEnabled(true));

// The required output intent
config.OutputIntent = new OutputIntent()
{
    Identifier = "ICC profile identifier",
    Url = "URL/to/ICC/profile"
};
// Color space conversion settings
config.ColorSpaceSettings = new ColorSpaceSettings
{
    // The same profile as the output intent, required for accurate conversion to CMYK
    CmykIccProfile = new Resource() { Uri = "URL/to/ICC/profile" },
    // Not necessary to set in this case (overridden by output intent), but recommended
    TargetColorSpace = ColorSpace.CMYK,
    // Enable conversion of RGB colors and images to CMYK
    ConversionEnabled = true
};

// The required output intent
config.outputIntent = {
    identifier: "ICC profile identifier",
    url: "URL/to/ICC/profile"
};
// Color space conversion settings
config.colorSpaceSettings = {
    // The same profile as the output intent, required for accurate conversion to CMYK
    cmykIccProfile: { uri: "URL/to/ICC/profile" },
    // Not necessary to set in this case (overridden by output intent), but recommended
    targetColorSpace: PDFreactor.ColorSpace.CMYK,
    // Enable conversion of RGB colors and images to CMYK
    conversionEnabled: true
};

// The required output intent
config.outputIntent = {
    identifier: "ICC profile identifier",
    url: "URL/to/ICC/profile"
};
// Color space conversion settings
config.colorSpaceSettings = {
    // The same profile as the output intent, required for accurate conversion to CMYK
    cmykIccProfile: { uri: "URL/to/ICC/profile" },
    // Not necessary to set in this case (overridden by output intent), but recommended
    targetColorSpace: PDFreactor.ColorSpace.CMYK,
    // Enable conversion of RGB colors and images to CMYK
    conversionEnabled: true
};

// The required output intent
$config["outputIntent"] = array(
    "identifier" => "ICC profile identifier",
    "url" => "URL/to/ICC/profile"
);
// Color space conversion settings
$config["colorSpaceSettings"] = array(
    // The same profile as the output intent, required for accurate conversion to CMYK
    "cmykIccProfile" => array("uri" => "URL/to/ICC/profile"),
    // Not necessary to set in this case (overridden by output intent), but recommended
    "targetColorSpace" => ColorSpace::CMYK,
    // Enable conversion of RGB colors and images to CMYK
    "conversionEnabled" => true
);

# The required output intent
config['outputIntent'] = {
    'identifier': "ICC profile identifier",
    'url': "URL/to/ICC/profile"
}
# Color space conversion settings
config['colorSpaceSettings'] = {
    # The same profile as the output intent, required for accurate conversion to CMYK
    'cmykIccProfile': { 'uri': "URL/to/ICC/profile" },
    # Not necessary to set in this case (overridden by output intent), but recommended
    'targetColorSpace': PDFreactor.ColorSpace.CMYK,
    # Enable conversion of RGB colors and images to CMYK
    'conversionEnabled' True
}

# The required output intent
config['outputIntent'] = {
    identifier: "ICC profile identifier",
    url: "URL/to/ICC/profile"
}
# Color space conversion settings
config['colorSpaceSettings'] = {
    # The same profile as the output intent, required for accurate conversion to CMYK
    cmykIccProfile: { uri: "URL/to/ICC/profile" },
    # Not necessary to set in this case (overridden by output intent), but recommended
    targetColorSpace: PDFreactor::ColorSpace::CMYK,
    # Enable conversion of RGB colors and images to CMYK
    conversionEnabled True
}

{
    "outputIntent": {
        "identifier": "ICC profile identifier",
        "url": "URL/to/ICC/profile"
    },
    "colorSpaceSettings": {
        "cmykIccProfile": { "uri": "URL/to/ICC/profile" },
        "targetColorSpace": "CMYK",
        "conversionEnabled": true
}

You can also create a web version, which is smaller and in RGB:

// (No output intent required)
// Color space conversion settings
config.setColorSpaceSettings(new ColorSpaceSettings()
    // When converting to RGB the profile is used for accurate conversion from CMYK
    .setCmykIccProfile(new Resource().setUri("URL/to/ICC/profile"))
    // Not necessary to set in this case (default), but recommended
    .setTargetColorSpace(ColorSpace.RGB)
    // Enable conversion of CMYK colors and images to RGB
    .setConversionEnabled(true));
// Reduce image sizes by resampling and compression
config.setUserStyleSheets(new Resource().setContent(
    // downsample images that (in the final layout)
    // have a resolution of more then 200dpi
    "* { -ro-image-resampling: 200dpi; "
    // recompress all images to JPEG with a quality of 90%
      + "-ro-image-recompression: jpeg(90%) }"));

// (No output intent required)
// Color space conversion settings
config.ColorSpaceSettings = new ColorSpaceSettings {
    // When converting to RGB the profile is used for accurate conversion from CMYK
    CmykIccProfile = new Resource() { Uri = "URL/to/ICC/profile" },
    // Not necessary to set in this case (default), but recommended
    TargetColorSpace = ColorSpace.RGB,
    // Enable conversion of CMYK colors and images to RGB
    ConversionEnabled = true
};
// Reduce image sizes by resampling and compression
config.UserStyleSheets = new List<Resource>
{
    new Resource
    {
        // downsample images that (in the final layout)
        // have a resolution of more then 200dpi
        // recompress all images to JPEG with a quality of 90%
        Content = "* { -ro-image-resampling: 200dpi; -ro-image-recompression: jpeg(90%) }"
    }
};

// (No output intent required)
// Color space conversion settings
config.colorSpaceSettings = {
    // When converting to RGB the profile is used for accurate conversion from CMYK
    cmykIccProfile: { uri: "URL/to/ICC/profile" },
    // Not necessary to set in this case (default), but recommended
    targetColorSpace: PDFreactor.ColorSpace.RGB,
    // Enable conversion of CMYK colors and images to RGB
    conversionEnabled: true
};
// Reduce image sizes by resampling and compression
config.userStyleSheets = [{
    // downsample images that (in the final layout)
    // have a resolution of more then 200dpi
    // recompress all images to JPEG with a quality of 90%
    content: "* { -ro-image-resampling: 200dpi; -ro-image-recompression: jpeg(90%) }"
}];

// (No output intent required)
// Color space conversion settings
config.colorSpaceSettings = {
    // When converting to RGB the profile is used for accurate conversion from CMYK
    cmykIccProfile: { uri: "URL/to/ICC/profile" },
    // Not necessary to set in this case (default), but recommended
    targetColorSpace: PDFreactor.ColorSpace.RGB,
    // Enable conversion of CMYK colors and images to RGB
    conversionEnabled: true
};
// Reduce image sizes by resampling and compression
config.userStyleSheets = [{
    // downsample images that (in the final layout)
    // have a resolution of more then 200dpi
    // recompress all images to JPEG with a quality of 90%
    content: "* { -ro-image-resampling: 200dpi; -ro-image-recompression: jpeg(90%) }"
}];

// (No output intent required)
// Color space conversion settings
$config["colorSpaceSettings"] = array(
    // When converting to RGB the profile is used for accurate conversion from CMYK
    "cmykIccProfile" => array("uri" => "URL/to/ICC/profile"),
    // Not necessary to set in this case (default), but recommended
    "targetColorSpace" => ColorSpace::RGB,
    // Enable conversion of CMYK colors and images to RGB
    "conversionEnabled" => true
);
// Reduce image sizes by resampling and compression
$config["userStyleSheets"] = array(
    array(
        // downsample images that (in the final layout)
        // have a resolution of more then 200dpi
        // recompress all images to JPEG with a quality of 90%
        "content" => "* { -ro-image-resampling: 200dpi; -ro-image-recompression: jpeg(90%) }"
    )
}];

# (No output intent required)
# Color space conversion settings
config['colorSpaceSettings'] = {
    # When converting to RGB the profile is used for accurate conversion from CMYK
    'cmykIccProfile': { 'uri': "URL/to/ICC/profile" },
    # Not necessary to set in this case (default), but recommended
    'targetColorSpace': PDFreactor.ColorSpace.RGB,
    # Enable conversion of CMYK colors and images to RGB
    'conversionEnabled': True
}
# Reduce image sizes by resampling and compression
config.userStyleSheets = [{
    # downsample images that (in the final layout)
    # have a resolution of more then 200dpi
    # recompress all images to JPEG with a quality of 90%
    'content': "* { -ro-image-resampling: 200dpi; -ro-image-recompression: jpeg(90%) }"
}]

# (No output intent required)
# Color space conversion settings
config.colorSpaceSettings = {
    # When converting to RGB the profile is used for accurate conversion from CMYK
    cmykIccProfile: { uri: "URL/to/ICC/profile" },
    # Not necessary to set in this case (default), but recommended
    targetColorSpace: PDFreactor::ColorSpace::RGB,
    # Enable conversion of CMYK colors and images to RGB
    conversionEnabled: true
}
# Reduce image sizes by resampling and compression
config.userStyleSheets = [{
    # downsample images that (in the final layout)
    # have a resolution of more then 200dpi
    # recompress all images to JPEG with a quality of 90%
    content: "* { -ro-image-resampling: 200dpi; -ro-image-recompression: jpeg(90%) }"
}]

{
    "colorSpaceSettings": {
        "cmykIccProfile": { "uri": "URL/to/ICC/profile" },
        "targetColorSpace": "RGB",
        "conversionEnabled": true
    },
    "userStyleSheets": [{
        "content": "* { -ro-image-resampling: 200dpi; -ro-image-recompression: jpeg(90%) }"
    }
}

If cmykIccProfile is not set, naive conversion, similar to the one of PDF viewers, is used.

Print Dialog Prompt

PDFreactor can be configured to immediately display a print dialog when a PDF file created with PDFreactor is opened. To do so, the printDialogPrompt configuration property must be used:

config.setPrintDialogPrompt(true);

config.PrintDialogPrompt = true;

$config["printDialogPrompt"] = true;

config['printDialogPrompt'] = True

config['printDialogPrompt'] = true

config.printDialogPrompt = true;

config.printDialogPrompt = true;

{ "printDialogPrompt": true }

Compression

There are several factors that contribute to a PDFs resulting file size, such as the number of pages and image resources. To achieve a smaller file size, you can use various compression methods which may be more or less effective depending on the exact use case.

* {
    -ro-image-resampling: 72dpi;
}

config.setDisablePdfStructureOptimization(true);

config.DisablePdfStructureOptimization = true;

$config["disablePdfStructureOptimization"] = true;

config['disablePdfStructureOptimization'] = True

config['disablePdfStructureOptimization'] = true

config.disablePdfStructureOptimization = true;

config.disablePdfStructureOptimization = true;

{ "disablePdfStructureOptimization": true }

Encryption and Restrictions

PDFreactor can protect generated PDF documents via 40 or 128 bit encryption.

To encrypt the output PDF, set the encryption strength to a value other than ENCRYPTION_NONE:

EncryptionSettings encryptionSettings = new EncryptionSettings();
encryptionSettings.setType(Encryption.AES_256);
config.setEncryptionSettings(encryptionSettings);

config.encryptionSettings = new EncryptionSettings
{
    Type = Encryption.AES_256
};

$config["encryptionSettings"] = array(
    "type" =>  Encryption::AES_256
);

config['encryptionSettings'] = {
    'mode': PDFreactor.Encryption.AES_256
}

config['encryptionSettings'] = {
    mode: PDFreactor::Encryption::AES_256
}

config.encryptionSettings {
    mode: PDFreactor.Encryption.AES_256
};

config.encryptionSettings {
    mode: PDFreactor.Encryption.AES_256
};

{ "encryptionSettings": {
        "type": "AES_256"
    }
}

When the PDF document is opened, the user has to supply the user password in order to view the content. When no user password is set, the PDF can be viewed by any user. In either case, certain restrictions are imposed. These can be suspended by supplying the owner password. You can set the passwords as follows:

EncryptionSettings encryptionSettings = new EncryptionSettings();
encryptionSettings.setUserPassword("upasswd");
encryptionSettings.setOwnerPassword("opasswd");
config.setEncryptionSettings(encryptionSettings);

config.encryptionSettings = new EncryptionSettings
{
    UserPassword = "upasswd",
    OwnerPassword = "opasswd"
};

$config["encryptionSettings"] = array(
    "userPassword" => "upasswd",
    "ownerPassword" => "opasswd"
);

config['encryptionSettings'] = {
    'userPassword': "upasswd",
    'ownerPassword': "opasswd"
}

config['encryptionSettings'] = {
    userPassword: "userPassword",
    ownerPassword: "ownerPassword"
}

config.encryptionSettings {
    userPassword: "upasswd",
    ownerPassword: "opasswd"
};

config.encryptionSettings {
    userPassword: "upasswd",
    ownerPassword: "opasswd"
};

{ "encryptionSettings": {
        "userPassword": "upasswd",
        "ownerPassword": "opasswd"
    }
}

Though not recommended for security reasons, both passwords can be omitted. However, the owner password must be specified for certain postprocessing steps, e.g. for digital signing or merging.

By default, all restrictions are imposed on the PDF document. You can, however, exclude selected ones by using the following configuration properties:

Viewer Preferences

You can configure the initial presentation of the document in the viewer by setting viewer preferences. Setting viewer preferences will activate / deactivate certain options of the viewer, for example it allows to hide the viewer's toolbar when the document is opened.

Note that these preferences are not enforced, i.e. if you decide to set the HIDE_TOOLBAR preference, the user can still display the toolbar again when viewing this PDF if he decides to do so. Setting this preference only affects the default state of the toolbar when the document is opened, but does not enforce this state.

Some viewer preferences also influence the default settings of the print dialog of the viewer.

You can set viewer preferences by using the configuration property viewerPreferences, e.g.:

config.setViewerPreferences(ViewerPreferences.PAGE_LAYOUT_SINGLE_PAGE,
    ViewerPreferences.DISPLAY_DOC_TITLE);

config.ViewerPreferences = new List<ViewerPreferences>
{
    ViewerPreferences.PAGE_LAYOUT_SINGLE_PAGE,
    ViewerPreferences.DISPLAY_DOC_TITLE
};

$config["viewerPreferences"] = new array(
    ViewerPreferences::PAGE_LAYOUT_SINGLE_PAGE
    ViewerPreferences::DISPLAY_DOC_TITLE
);

config['viewerPreferences'] = [
    PDFreactor.ViewerPreferences.PAGE_LAYOUT_SINGLE_PAGE
    PDFreactor.ViewerPreferences.DISPLAY_DOC_TITLE
]

config['viewerPreferences'] = [
    PDFreactor::ViewerPreferences::PAGE_LAYOUT_SINGLE_PAGE
    PDFreactor::ViewerPreferences::DISPLAY_DOC_TITLE
]

config.viewerPreferences = [
    PDFreactor.ViewerPreferences.PAGE_LAYOUT_SINGLE_PAGE
    PDFreactor.ViewerPreferences.DISPLAY_DOC_TITLE
];

config.viewerPreferences = [
    PDFreactor.ViewerPreferences.PAGE_LAYOUT_SINGLE_PAGE
    PDFreactor.ViewerPreferences.DISPLAY_DOC_TITLE
];

{ "viewerPreferences": [ "PAGE_LAYOUT_SINGLE_PAGE", "DISPLAY_DOC_TITLE" ]}

PDFreactor supports the following viewer preferences:

Merging PDFs

A generated PDF can easily be merged with existing ones. To merge with a single PDF or multiple PDFs use the mergeDocuments configuration property that declares either URLs to or binary data of existing PDF files.

MergeSettings mergeSettings = new MergeSettings();
mergeSettings.setMergeDocuments(
    new Resource().setUri("https://www.myserver.com/overlaid1.pdf"),
    new Resource().setData(pdfBytes));
config.setMergeSettings(mergeSettings);

config.mergeSettings = new MergeSettings 
{
    MergeDocuments = new List<Resource>
    {
        new Resource { Uri = "https://www.myserver.com/overlaid1.pdf" },
        new Resource { Data = pdfBytes }
    }
};

$config["mergeSettings"] = array(
    "mergeDocuments" => [
        array("uri" => "https://www.myserver.com/overlaid1.pdf"),
        array("data" => pdfBytesAsBase64)
    ] 
);

config['mergeSettings'] = {
    'mergeDocuments': [
        { 'uri': "https://www.myserver.com/overlaid1.pdf" },
        { 'data': pdfBytesAsBase64 }
    ]
}

config['mergeSettings'] = {
    mergeDocuments: [
        { uri: "https://www.myserver.com/overlaid1.pdf" },
        { data: pdfBytesAsBase64 }
    ]                  
}

config.mergeSettings = {
    mergeDocuments: [
        { uri: "https://www.myserver.com/overlaid1.pdf" },
        { data: pdfBytesAsBase64 }
    ]
};

config.mergeSettings = {
    mergeDocuments: [
        { uri: "https://www.myserver.com/overlaid1.pdf" },
        { data: pdfBytesAsBase64 }
    ]
};

{ "mergeSettings": {
        "mergeDocuments": [
            { "uri": "https://www.myserver.com/overlaid1.pdf" },
            { "data": pdfBytesAsBase64 }
        ]
    }
}

Whether the generated PDF is appended or laid over the existing PDFs depends on the general type of merge:

• Concatenation

• Arrange

• Overlay

Concatenation merges append the generated PDF before or after the existing ones. The following sample shows how to append the generated PDF after the existing one:

MergeSettings mergeSettings = new MergeSettings();
mergeSettings
    .setMergeDocuments(
        new Resource().setUri("https://www.myserver.com/appendDoc.pdf"))
    .setMode(MergeMode.APPEND);
config.setMergeSettings(mergeSettings);

config.mergeSettings = new MergeSettings 
{
    MergeDocuments = new List<Resource>
    {
        new Resource { Uri = "https://www.myserver.com/appendDoc.pdf" }
    },
    Mode = MergeMode.APPEND
};

$config["mergeSettings"] = array(
    "mergeDocuments" => [
        array("uri" => "https://www.myserver.com/appendDoc.pdf"")
    ],
    "mode" => MergeMode::APPEND
);

config['mergeSettings'] = {
    'mergeDocuments': [
        { 'uri': "https://www.myserver.com/appendDoc.pdf" }
    ],
    'mode': PDFreactor.MergeMode.APPEND
}

config['mergeSettings'] = {
    mergeDocuments: [
        { uri: "https://www.myserver.com/appendDoc.pdf" }
    ]  ,
    mode: PDFreactor::MergeMode::APPEND                
}

config.mergeSettings = {
    mergeDocuments: [
        { uri: "https://www.myserver.com/appendDoc.pdf" }
    ],
    mode: PDFreactor.MergeMode.APPEND
};

config.mergeSettings = {
    mergeDocuments: [
        { uri: "https://www.myserver.com/appendDoc.pdf" }
    ],
    mode: PDFreactor.MergeMode.APPEND
};

{ "mergeSettings": {
        "mergeDocuments": [
            { "uri": "https://www.myserver.com/appendDoc.pdf" }
        ],
        "mode": "APPEND"
    }
}

To append the generated PDF before the existing ones use MergeMode.PREPEND.

Arrange inserts specified pages of PDFs into the generated PDF. This merge mode has to be combined with pageOrder (see ) in order to specify which page should be inserted where. The following sample shows how to insert the first page of an existing PDF after the second page of the generated one:

MergeSettings mergeSettings = new MergeSettings();
mergeSettings
    .setMergeDocuments(
        new Resource().setUri("https://www.myserver.com/insert1.pdf"),
        new Resource().setUri("https://www.myserver.com/insert2.pdf"))
    .setMode(MergeMode.ARRANGE);
config.setMergeSettings(mergeSettings);
config.setPageOrder("1,1:1,2..-1");

config.MergeSettings = new MergeSettings
{
    MergeDocuments = new List<Resource>
    {
        new Resource { Uri = "https://www.myserver.com/insert1.pdf" },
        new Resource { Uri = "https://www.myserver.com/insert2.pdf" }
    },
    Mode = MergeMode.ARRANGE
};
config.PageOrder = "1,1:1,2..-1";

$config["mergeSettings"] = array(
    "mergeDocuments" => [
        array("uri" => "https://www.myserver.com/insert1.pdf"),
        array("uri" => "https://www.myserver.com/insert2.pdf")
    ],
    "mode" => MergeMode::ARRANGE
);
$config["pageOrder"] = "1,1:1,2..-1";

config['mergeSettings'] = {
    'mergeDocuments' = [
        { 'uri': "https://www.myserver.com/insert1.pdf" },
        { 'uri': "https://www.myserver.com/insert2.pdf" }
    ],
    'mode': PDFreactor.MergeMode.ARRANGE
}
config['pageOrder'] = "1,1:1,2..-1"

config['mergeSettings'] = {
    mergeDocuments: [
        { uri: "https://www.myserver.com/insert1.pdf" },
        { uri: "https://www.myserver.com/insert2.pdf" }
    ],
    mode: PDFreactor::MergeMode::ARRANGE
}
config['pageOrder'] = "1,1:1,2..-1"

config.mergeSettings = {
    mergeDocuments: [
        { uri: "https://www.myserver.com/insert1.pdf" },
        { uri: "https://www.myserver.com/insert2.pdf" }
    ],
    mode: PDFreactor.MergeMode.ARRANGE
}
config.pageOrder = "1,1:1,2..-1";

config.mergeSettings = {
    mergeDocuments: [
        { uri: "https://www.myserver.com/insert1.pdf" },
        { uri: "https://www.myserver.com/insert2.pdf" }
    ],
    mode: PDFreactor.MergeMode.ARRANGE
}
config.pageOrder = "1,1:1,2..-1";

{ "mergeSettings": {
        "mergeDocuments": [
            { "uri": "https://www.myserver.com/insert1.pdf" },
            { "uri": "https://www.myserver.com/insert2.pdf" }
        ],
        "mode": "ARRANGE"
    }
    "pageOrder": "1,1:1,2..-1" 
}

More information on the syntax can be found at

Overlay merges add the generated PDF above or below existing PDFs. The following sample shows how to overlay an existing PDF:

MergeSettings mergeSettings = new MergeSettings();
mergeSettings
    .setMergeDocuments(
        new Resource().setUri("https://www.myserver.com/overlaid.pdf"))
    .setMode(MergeMode.OVERLAY);
config.setMergeSettings(mergeSettings);

config.mergeSettings = new MergeSettings 
{
    MergeDocuments = new List<Resource>
    {
        new Resource { Uri = "https://www.myserver.com/overlaid.pdf" }
    },
    Mode = MergeMode.OVERLAY
};

$config["mergeSettings"] = array(
    "mergeDocuments" => [
        array("uri" => "https://www.myserver.com/overlaid.pdf")
    ],
    "mode" => MergeMode::OVERLAY
);

config['mergeSettings'] = {
    'mergeDocuments': [
        { 'uri': "https://www.myserver.com/overlaid.pdf" }
    ],
    'mode': PDFreactor.MergeMode.OVERLAY
}

config['mergeSettings'] = {
    mergeDocuments: [
        { uri: "https://www.myserver.com/overlaid.pdf" }
    ],
    mode: PDFreactor::MergeMode::OVERLAY                
}

config.mergeSettings = {
    mergeDocuments: [
        { uri: "https://www.myserver.com/overlaid.pdf" }
    ],
    mode: PDFreactor.MergeMode.OVERLAY
};

config.mergeSettings = {
    mergeDocuments: [
        { uri: "https://www.myserver.com/overlaid.pdf" }
    ],
    mode: PDFreactor.MergeMode.OVERLAY
};

{ "mergeSettings": {
        "mergeDocuments": [
            { "uri": "https://www.myserver.com/overlaid.pdf" }
        ],
        "mode": "OVERLAY"
    }
}

To add the generated PDF below the existing one use MergeMode.OVERLAY_BELOW.

PDFreactor allows to repeat the pages of PDFs with less pages than other PDFs involved in the merger. The configuration property overlayRepeat offers different options to do this:

• repeat only the last page

• repeat all pages of the PDF

• do not repeat any pages

• trim to page count of the shorter document

In the following example, all pages are repeated:

MergeSettings mergeSettings = new MergeSettings();
mergeSettings
    .setMergeDocuments(
        new Resource().setUri("https://www.myserver.com/overlaid.pdf"))
    .setMode(MergeMode.OVERLAY)
    .setOverlayRepeat(OverlayRepeat.ALL_PAGES);
config.setMergeSettings(mergeSettings);

config.mergeSettings = new MergeSettings 
{
    MergeDocuments = new List<Resource>
    {
        new Resource { Uri = "https://www.myserver.com/overlaid.pdf" }
    },
    Mode = MergeMode.OVERLAY,
    OverlayRepeat = OverlayRepeat.ALL_PAGES
};

$config["mergeSettings"] = array(
    "mergeDocuments" => [
        array("uri" => "https://www.myserver.com/overlaid.pdf"")
    ],
    "mode" => MergeMode::OVERLAY,
    "overlayRepeat" => OverlayRepeat::ALL_PAGES
);

config['mergeSettings'] = {
    'mergeDocuments': [
        { 'uri': "https://www.myserver.com/overlaid.pdf" }
    ],
    'mode': PDFreactor.MergeMode.OVERLAY,
    'overlayRepeat': PDFreactor.OverlayRepeat.ALL_PAGES
}

config['mergeSettings'] = {
    mergeDocuments: [
        { uri: "https://www.myserver.com/overlaid.pdf" }
    ],
    mode: PDFreactor::MergeMode::OVERLAY,
    overlayRepeat: PDFreactor::OverlayRepeat::ALL_PAGES            
}

config.mergeSettings = {
    mergeDocuments: [
        { uri: "https://www.myserver.com/overlaid.pdf" }
    ],
    mode: PDFreactor.MergeMode.OVERLAY,
    overlayRepeat: PDFreactor.OverlayRepeat.ALL_PAGES
};

config.mergeSettings = {
    mergeDocuments: [
        { uri: "https://www.myserver.com/overlaid.pdf" }
    ],
    mode: PDFreactor.MergeMode.OVERLAY,
    overlayRepeat: PDFreactor.OverlayRepeat.ALL_PAGES
};

{ "mergeSettings": {
        "mergeDocuments": [
            { "uri": "https://www.myserver.com/overlaid.pdf" }
        ],
        "mode": "OVERLAY",
        "overlayRepeat": "ALL_PAGES"
    }
}

The default merge behavior of PDFreactor is a concatenation after the pages of the existing PDFs.

When overlaying documents that have differing page sizes, use the overlayFit property to configure how overlay pages that have different dimensions from thepages they are overlaying should be resized.

In the following example, the overlaying page keeps its aspect ratio but will be clipped to fit:

MergeSettings mergeSettings = new MergeSettings();
mergeSettings
    .setMergeDocuments(
        new Resource().setUri("https://www.myserver.com/overlaid.pdf"))
    .setMode(MergeMode.OVERLAY)
    .setOverlayFit(OverlayFit.COVER);
config.setMergeSettings(mergeSettings);

config.mergeSettings = new MergeSettings 
{
    MergeDocuments = new List<Resource>
    {
        new Resource { Uri = "https://www.myserver.com/overlaid.pdf" }
    },
    Mode = MergeMode.OVERLAY,
    OverlayFit = OverlayFit.COVER
};

$config["mergeSettings"] = array(
    "mergeDocuments" => [
        array("uri" => "https://www.myserver.com/overlaid.pdf"")
    ],
    "mode" => MergeMode::OVERLAY,
    "overlayFit" => OverlayFit::COVER
);

config['mergeSettings'] = {
    'mergeDocuments': [
        { 'uri': "https://www.myserver.com/overlaid.pdf" }
    ],
    'mode': PDFreactor.MergeMode.OVERLAY,
    'overlayFit': PDFreactor.OverlayFit.COVER
}

config['mergeSettings'] = {
    mergeDocuments: [
        { uri: "https://www.myserver.com/overlaid.pdf" }
    ],
    mode: PDFreactor::MergeMode::OVERLAY,
    overlayFit: PDFreactor::OverlayFit::COVER            
}

config.mergeSettings = {
    mergeDocuments: [
        { uri: "https://www.myserver.com/overlaid.pdf" }
    ],
    mode: PDFreactor.MergeMode.OVERLAY,
    overlayFit: PDFreactor.OverlayFit.COVER
};

config.mergeSettings = {
    mergeDocuments: [
        { uri: "https://www.myserver.com/overlaid.pdf" }
    ],
    mode: PDFreactor.MergeMode.OVERLAY,
    overlayFit: PDFreactor.OverlayFit.COVER
};

{ "mergeSettings": {
        "mergeDocuments": [
            { "uri": "https://www.myserver.com/overlaid.pdf" }
        ],
        "mode": "OVERLAY",
        "overlayFit": "COVER"
    }
}

When overlaying pages, annotations present in the overlay are preserved by default. This behaviour can be configured using the property disableOverlayAnnotations.

The following example shows how to disable overlay annotations so that they are not embedded:

MergeSettings mergeSettings = new MergeSettings();
mergeSettings
    .setMergeDocuments(
        new Resource().setUri("https://www.myserver.com/overlaid.pdf"))
    .setMode(MergeMode.OVERLAY)
    .setDisableOverlayAnnotations(true);
config.setMergeSettings(mergeSettings);

config.mergeSettings = new MergeSettings 
{
    MergeDocuments = new List<Resource>
    {
        new Resource { Uri = "https://www.myserver.com/overlaid.pdf" }
    },
    Mode = MergeMode.OVERLAY,
    DisableOverlayAnnotations = true
};

$config["mergeSettings"] = array(
    "mergeDocuments" => [
        array("uri" => "https://www.myserver.com/overlaid.pdf"")
    ],
    "mode" => MergeMode::OVERLAY,
    "disableOverlayAnnotations" => true
);

config['mergeSettings'] = {
    'mergeDocuments': [
        { 'uri': "https://www.myserver.com/overlaid.pdf" }
    ],
    'mode': PDFreactor.MergeMode.OVERLAY,
    'disableOverlayAnnotations': true
}

config['mergeSettings'] = {
    mergeDocuments: [
        { uri: "https://www.myserver.com/overlaid.pdf" }
    ],
    mode: PDFreactor::MergeMode::OVERLAY,
    disableOverlayAnnotations: true            
}

config.mergeSettings = {
    mergeDocuments: [
        { uri: "https://www.myserver.com/overlaid.pdf" }
    ],
    mode: PDFreactor.MergeMode.OVERLAY,
    disableOverlayAnnotations: true
};

config.mergeSettings = {
    mergeDocuments: [
        { uri: "https://www.myserver.com/overlaid.pdf" }
    ],
    mode: PDFreactor.MergeMode.OVERLAY,
    disableOverlayAnnotations: true
};

{ "mergeSettings": {
        "mergeDocuments": [
            { "uri": "https://www.myserver.com/overlaid.pdf" }
        ],
        "mode": "OVERLAY",
        "disableOverlayAnnotations": true
    }
}

By default, merging documents will if exceptions occur during the merge operation. If you want the merge to proceed and merge documents with errors simply to be omitted if they contain errors, you can enable the error policy IGNORE_INVALID_MERGE_DOCUMENTS_EXCEPTION to do so. Please see Error Policies for details.

Digital Signing

PDFreactor is able to sign the PDFs it creates. This allows to validate the identity of the creator of the document. A self-signed certificate may be used. A keystore file in which the certificate is included, is required to sign PDFs with PDFreactor.

The keystore type is required to be one of the following formats:

• "pkcs12"

• "jks"

PDFreactor supports various certificates types to sign a PDF such as self-signed certificates. Please see the API documentation for details on these modes.

To sign a PDF digitally use the configuration property signPDF:

config.setSignPDF(
new SignPDF()
    .setKeyAlias("keyAlias")
    .setKeystorePassword("keyStorePassword")
    .setKeystoreType(KeystoreType.JKS)
    .setKeystoreURL("http://myServer/Keystore.jks")
    .setSigningMode(SigningMode.SELF_SIGNED));

config.SignPDF = new SignPDF
{
    KeyAlias = "keyAlias",
    KeystorePassword = "keyStorePassword",
    KeystoreType = KeystoreType.JKS,
    KeystoreURL = "http://myServer/Keystore.jks",
    SigningMode = SigningMode.SELF_SIGNED
};

$config["signPDF"] = array(
    "keyAlias" => "keyAlias",
    "keystorePassword" => "keyStorePassword",
    "keystoreType" => KeystoreType::JKS,
    "keystoreURL" => "http://myServer/Keystore.jks",
    "signingMode" => SigningMode::SELF_SIGNED
);

config['signPDF'] = {
    'keyAlias': "keyAlias",
    'keystorePassword': "keyStorePassword",
    'keystoreType': PDFreactor.KeystoreType.JKS,
    'keystoreURL': "http://myServer/Keystore.jks",
    'signingMode': PDFreactor.SigningMode.SELF_SIGNED
}

config['signPDF'] = {
    keyAlias: "keyAlias",
    keystorePassword: "keyStorePassword",
    keystoreType: PDFreactor::KeystoreType::JKS,
    keystoreURL: "http://myServer/Keystore.jks",
    signingMode: PDFreactor::SigningMode::SELF_SIGNED
}

config.signPDF = {
    keyAlias: "keyAlias",
    keystorePassword: "keyStorePassword",
    keystoreType: PDFreactor.KeystoreType.JKS,
    keystoreURL: "http://myServer/Keystore.jks",
    signingMode: PDFreactor.SigningMode.SELF_SIGNED
};

config.signPDF = {
    keyAlias: "keyAlias",
    keystorePassword: "keyStorePassword",
    keystoreType: PDFreactor.KeystoreType.JKS,
    keystoreURL: "http://myServer/Keystore.jks",
    signingMode: PDFreactor.SigningMode.SELF_SIGNED
};

{ "signPDF": {
    "keyAlias": "keyAlias",
    "keystorePassword": "keyStorePassword",
    "keystoreType": PDFreactor.KeystoreType.JKS,
    "keystoreURL": "http://myServer/Keystore.jks",
    "signingMode": PDFreactor.SigningMode.SELF_SIGNED
}}

Font Embedding

By default, PDFreactor automatically embeds the required subsets of all fonts used in the document. This can be disable using the configuration property disableFontEmbedding.

config.setDisableFontEmbedding(true);

config.DisableFontEmbedding = true;

$config["disableFontEmbedding"] = true;

config['disableFontEmbedding'] = True

config['disableFontEmbedding'] = true

config.disableFontEmbedding = true;

config.disableFontEmbedding = true;

{ "disableFontEmbedding": true }

Doing so reduces the file size of the resulting PDF documents. However, these documents are likely to not look the same on all systems. Therefore this property should only be used when necessary.

Overprinting

Overprinting means that one color is printed on top of another color. For example, a background is printed completely, before the text is put on top. As this is a feature for printing it should be used with CMYK colors.

PDFreactor can set the values of the PDF graphics state parameters "overprint" and "overprint mode" via CSS. However, before the CSS properties have any effect, overprinting must first be enabled via the configuration property addOverprint:

config.setAddOverprint(true);

config.AddOverprint = true;

$config["addOverprint"] = true;

config['addOverprint'] = True

config['addOverprint'] = true

config.addOverprint = true;

config.addOverprint = true;

{ "addOverprint": true }

Then using the styles -ro-pdf-overprint and -ro-pdf-overprint-content you can specify the overprint properties of elements and their content to either none (default), mode0 or mode1 (nonzero overprint mode).

-ro-pdf-overprint affects the entire element, while -ro-pdf-overprint-content only affects the content of the element (not its borders and backgrounds). In both cases the children of the element are affected entirely, unless overprint styles are applied to them as well.

The following example sets small text on solid background to overprint, without enabling overprinting for the background of either the paragraphs or the highlighting spans:

p.infobox {
    border: 1pt solid black;
    background-color: lightgrey;
    color: black;
    font-size: 8pt;
    -ro-pdf-overprint-content: mode1;
}
p.infobox span.marked {
    background-color: yellow;
    -ro-pdf-overprint: none;
    -ro-pdf-overprint-content: mode1;
}

Attachments

Alternatively to linking to external URLs (see ) PDFreactor also allows embedding their content into the PDF.

Attachments can be defined via CSS, which can be enabled by the configuration property addAttachments:

config.setAddAttachments(true);

config.AddAttachments = true;

$config["addAttachments"] = true;

config['addAttachments'] = True

config['addAttachments'] = true

config.addAttachments = true;

config.addAttachments = true;

{ "addAttachments": true }

The following styles can be used to specify attachments:

• :

  A URL pointing to the file to be embedded. This URL can be relative.

• :

  The file name associated with the attachment. It is recommended to specify the correct file extension. If this is not specified the name is derived from the URL.

• :

  The description of the attachment. If this is not specified the name is used.

• :

  • element (default): The attachment is related to the area of the element. Viewers may show a marker near that area.

  • document: The file is attached to the document with no relation to the element.

Attachments can be specified for specific elements as follows:

#downloadReport {
    -ro-pdf-attachment-url: "../resources/0412/report.doc";
    -ro-pdf-attachment-name: "report-2012-04.doc";
    -ro-pdf-attachment-description: "Report for April of 2012";
}

Strings can be dynamically read from the document using the CSS functions attr and , that read specified attributes or the text content of the element respectively. Using those, certain a-tags can be changed from links to attachments:

.downloadReports a[href] {
    -ro-link: none;
    -ro-pdf-attachment-url: attr(href);
    -ro-pdf-attachment-description: content() " (" attr(href) ")";
}

Attachments can also be set via the configuration property attachments. This configuration property also allows specifying the content of the attachment as a byte array instead of an URL, so dynamically created data can be attached:

config.setAttachments(
    new Attachment()
        .setData("sample attachment text".getBytes())
        .setName("sample.txt")
        .setDescription("a dynamically created attachment containing text"),
    new Attachment()
        .setUrl("../resources/0412/report.doc")
        .setName("report-2012-04.doc")
        .setDescription("Report for April of 2012"));

config.Attachments = new List<Attachment>
{
    new Attachment
    {
        Data = sampleAttachmentTextBytes
        Name = "sample.txt"
        Description = "a dynamically created attachment containing text"
    },
    new Attachment
    {
        Url = "../resources/0412/report.doc",
        Name = "report-2012-04.doc",
        Description = "Report for April of 2012"
    }
};

$config["attachments"] = array(
    array(
        "data" => sampleAttachmentTextBytesAsBase64
        "name" => "sample.txt"
        "description" => "a dynamically created attachment containing text"
    ),
    array(
        "url" => "../resources/0412/report.doc",
        "name" => "report-2012-04.doc",
        "description" => "Report for April of 2012"
    )
);

config['attachments'] = [
    {
        'data': sampleAttachmentTextBytesAsBase64
        'name': "sample.txt"
        'description': "a dynamically created attachment containing text"
    },
    {
        'url': "../resources/0412/report.doc",
        'name': "report-2012-04.doc",
        'description': "Report for April of 2012"
    }
]

config['attachments'] = [
    {
        data: sampleAttachmentTextBytesAsBase64
        name: "sample.txt"
        description: "a dynamically created attachment containing text"
    },
    {
        url: "../resources/0412/report.doc",
        name: "report-2012-04.doc",
        description: "Report for April of 2012"
    }
]

config.attachments = [
    {
        data: sampleAttachmentTextBytesAsBase64
        name: "sample.txt"
        description: "a dynamically created attachment containing text"
    },
    {
        url: "../resources/0412/report.doc",
        name: "report-2012-04.doc",
        description: "Report for April of 2012"
    }
];

config.attachments = [
    {
        data: sampleAttachmentTextBytesAsBase64
        name: "sample.txt"
        description: "a dynamically created attachment containing text"
    },
    {
        url: "../resources/0412/report.doc",
        name: "report-2012-04.doc",
        description: "Report for April of 2012"
    }
];

{ "attachments": [
    {
        data: sampleAttachmentTextBytesAsBase64
        name: "sample.txt"
        description: "a dynamically created attachment containing text"
    },
    {
        url: "../resources/0412/report.doc",
        name: "report-2012-04.doc",
        description: "Report for April of 2012"
    }
]}

PDF Script

Some PDF viewers (e.g. Adobe Reader) allow the execution of JavaScript, which has been added to the PDF. This way, the document can be changed and dynamic content can be added long after the conversion is complete. Of course the structure of the PDF is different from the HTML and addressing certain elements with PDF scripts has to be done differently.

Please note, that support for PDF scripts is not wide spread among PDF reader software.

PDFreactor allows to add such scripts using the configuration property pdfScriptAction. The parameters are the script as a string and the event which should trigger the script.

The supported events are:

• open: These scripts are triggered when opening the PDF in a viewer.

• close: These scripts are triggered when closing the PDF.

• before save: These events are triggered just before the viewer saves the PDF.

• after save: These events are triggered after the viewer has saved the PDF.

• before print: These events are triggered just before the viewer prints the PDF.

• after print: These events are triggered after the viewer has printed the PDF.

config.setPdfScriptAction(new PdfScriptAction()
    .setScript("app.alert('hello');")
    .setTriggerEvent(PdfScriptTriggerEvent.OPEN));

config.PdfScriptAction = new PdfScriptAction
{
    Script = "app.alert('hello');",
    TriggerEvent = PdfScriptTriggerEvent.OPEN
};

$config["pdfScriptAction"] = array(
    "script" => "app.alert('hello');",
    "triggerEvent" => PdfScriptTriggerEvent::OPEN
);

config['pdfScriptAction'] = {
    'script': "app.alert('hello');",
    'triggerEvent': PDFreactor.PdfScriptTriggerEvent.OPEN
}

config['pdfScriptAction'] = {
    script: "app.alert('hello');",
    triggerEvent: PDFreactor::PdfScriptTriggerEvent::OPEN
}

config.pdfScriptAction = {
    script: "app.alert('hello');",
    triggerEvent: PDFreactor.PdfScriptTriggerEvent.OPEN
};

config.pdfScriptAction = {
    script: "app.alert('hello');",
    triggerEvent: PDFreactor.PdfScriptTriggerEvent.OPEN
};

{ "pdfScriptAction": {
    "script": "app.alert('hello');",
    "triggerEvent": "OPEN"
}}

Preview Images

While most PDF viewers automatically generate page thumbnails to preview pages, PDFreactor can do this during the conversion and embed these preview images. This frees up PDF viewer resources and is especially useful for large documents. You can let PDFreactor create preview images with the addPreviewImages configuration property like this:

config.setAddPreviewImages(true);

config.AddPreviewImages = true;

$config["addPreviewImages"] = true;

config['addPreviewImages'] = True

config['addPreviewImages'] = true

config.addPreviewImages = true;

config.addPreviewImages = true;

{ "addPreviewImages": true }

Custom XMP

When using conformance such as PDF/A, PDF/X or PDF/UA as well as other features, PDFreactor automatically creates and appends an appropriate XMP to the generated PDF.

Custom XMPs can be loaded via content or uri. You also need to specify a priority, which can be HIGH (which means that the custom XMP replaces the one generated by PDFreactor) or LOW (which means that the custom XMP is only attached if PDFreactor did not generate one).

config.setXmp(new Xmp()
    .setPriority(XmpPriority.HIGH)
    .setUri("http://cdn/myXmp.xml"));

config.Xmp = new Xmp {
    Priority = XmpPriority.HIGH,
    Uri = "http://cdn/myXmp.xml"
};

$config["xmp"] = array(
    "priority" => XmpPriority::HIGH,
    "uri" => "http://cdn/myXmp.xml"
);

config['xmp'] = {
    'priority': PDFreactor.XmpPriority.HIGH,
    'uri': 'http://cdn/myXmp.xml'
}

config['xmp'] = {
    priority: PDFreactor::XmpPriority::HIGH,
    uri: 'http://cdn/myXmp.xml'
}

config.xmp = {
    priority: PDFreactor.XmpPriority.HIGH,
    uri: "http://cdn/myXmp.xml"
};

config.xmp = {
    priority: PDFreactor.XmpPriority.HIGH,
    uri: "http://cdn/myXmp.xml"
};

{ "xmp": {
    "priority": "HIGH",
    "uri": "http://cdn/myXmp.xml"
}}

Selecting a page

All image output formats, except for the TIFF formats, create an image of a single page. By default, this is the first page. A different page can be selected using the configuration property pageOrder, e.g.:

config.setPageOrder("5");

config.PageOrder = "5";

$config["pageOrder"] = "5";

config['pageOrder'] = "5"

config['pageOrder'] = "5"

config.pageOrder = "5";

config.pageOrder = "5";

{ "pageOrder": "5" }

Converting a Document Into Multiple Images

To convert a document into multiple images, you have to set the multiImage parameter of your OutputFormat to true e.g. like this:

config.setOutputFormat(new OutputFormat()
    .setType(OutputType.PNG)
    .setWidth(512)
    .setHeight(-1)
    .setMultiImage(true));

config.OutputFormat = new OutputFormat {
    Type = OutputType.PNG,
    Width = 512,
    Height = -1,
    MultiImage = true
};

$config["outputFormat"] = array(
    "type" => OutputType::PNG,
    "width" => 512,
    "height" => -1,
    "multiImage" => true
);

config['outputFormat'] = {
    'type': PDFreactor.OutputType.PNG,
    'width': 512,
    'height': -1,
    'multiImage': True
}

config['outputFormat'] = {
    type: PDFreactor::OutputType::PNG,
    width: 512,
    height: -1,
    multiImage: true
}

config.outputFormat = {
    type: PDFreactor.OutputType.PNG,
    width: 512,
    height: -1,
    multiImage: true
};

config.outputFormat = {
    type: PDFreactor.OutputType.PNG,
    width: 512,
    height: -1,
    multiImage: true
};

{ "outputFormat": {
    "type": "PNG",
    "width": 512,
    "height": -1,
    "multiImage": true
}}

The documentArray property of the Result object then returns an array of byte arrays, each containing an image representing one page of the document.

Continuous Output

The configuration property continuousOutput sets PDFreactor to continuous mode. In this mode each document is converted into one image. Also screen styles will be used and print styles will be ignored, resulting in a very browser-like look for the output image.

config.setContinuousOutput(new ContinuousOutput()
    .setWidth(1024)
    .setHeight(768));

config.ContinuousOutput = new ContinuousOutput {
    Width = 1024,
    Height = 768
};

$config["continuousOutput"] = array(
    "width" => 1024,
    "height" => 768
);

config['continuousOutput'] = {
    'width': 1024,
    'height': 768
}

config['continuousOutput'] = {
    width: 1024,
    height: 768
}

config.continuousOutput = {
    width: 1024,
    height: 768
};

config.continuousOutput = {
    width: 1024,
    height: 768
};

{ "continuousOutput": {
    "width": 1024,
    "height": 768
}}

The first parameter sets the width of the layout. This has the same effect as the width of a browser window. This only changes the layout. The result will still be scaled to the width specified by outputFormat The second parameter sets the height. This has the same effect as the height of a browser window, i.e. it will cut off the image or increase its height. Values of less than 1 cause the laid out height of the document to be used.

Grayscale Image

PDFreactor can optionally output images that are entirely grayscale, i.e. that are composed exclusively of shades of gray via the forceGrayscaleImage configuration property.

config.setForceGrayscaleImage(true);

config.ForceGrayscaleImage = true;

$config["forceGrayscaleImage"] = true;

config['forceGrayscaleImage'] = True

config['forceGrayscaleImage'] = true

config.forceGrayscaleImage = true;

config.forceGrayscaleImage = true;

{ "forceGrayscaleImage": true }

Color Space Conversion

For JPEG and (non-CCITT) TIFF output the images can be converted to CMYK before encoding. Conversion is done using a specified ICC profile or naively if there is none.

config.setColorSpaceSettings(new ColorSpaceSettings()
    .setConversionEnabled(true)
    .setTargetColorSpace(ColorSpace.CMYK)
    .setCmykIccProfile(new Resource().setUri("URL/to/optional/ICC/profile")));

config.ColorSpaceSettings = new ColorSpaceSettings
{
    ConversionEnabled = true,
    TargetColorSpace = ColorSpace.CMYK,
    CmykIccProfile = new Resource() { Uri = "URL/to/optional/ICC/profile" }
};

config.colorSpaceSettings = {
    conversionEnabled: true,
    targetColorSpace: PDFreactor.ColorSpace.CMYK,
    cmykIccProfile: { uri: "URL/to/optional/ICC/profile" }
};

config.colorSpaceSettings = {
    conversionEnabled: true,
    targetColorSpace: PDFreactor.ColorSpace.CMYK,
    cmykIccProfile: { uri: "URL/to/optional/ICC/profile" }
};

$config["colorSpaceSettings"] = array(
    "conversionEnabled" => true,
    "targetColorSpace" => ColorSpace::CMYK,
    "cmykIccProfile" => array("uri" => "URL/to/optional/ICC/profile")
);

config['colorSpaceSettings'] = {
    'conversionEnabled' True,
    'targetColorSpace': PDFreactor.ColorSpace.CMYK,
    'cmykIccProfile': { 'uri': "URL/to/optional/ICC/profile" }
}

config['colorSpaceSettings'] = {
    conversionEnabled True,
    targetColorSpace: PDFreactor::ColorSpace::CMYK,
    cmykIccProfile: { uri: "URL/to/optional/ICC/profile" }
}

{
    "colorSpaceSettings": {
        "conversionEnabled": true,
        "targetColorSpace": "CMYK",
        "cmykIccProfile": { "uri": "URL/to/optional/ICC/profile" }
}

Layout at Breaks

Boxes around or next to breaks are subject to minor adjustments depending on the situation:

h1 {
    break-before: page;
    margin-top: 0;
}

div.multiColumn > *:first-child {
    margin-top: 0;
}

Page Selectors

To create an individual page layout pages need to be selected with CSS. In principle it works the same way as selecting an element, but the selector is different.

To select all pages of the document, the @page rule is used instead of the usual element selector.

@page {
    margin: 1in;
}

:first, :left, :right and other page specific pseudo-classes make it possible to style specific pages, like the first ones, e.g. for cover pages or subsets, like left pages.

@page {
    margin: 0.5in;
}
@page:left {
    margin-right: 0.75in;
}
@page:right {
    margin-left: 0.75in;
}

Page Size & Orientation

The size and orientation of a page can be set with the property. PDFreactor supports many different page sizes, see Appendix Supported Page Size Formats.

@page {
    size: letter portrait;
}

To set a page to landscape orientation, "portrait" is replaced by "landscape":

@page {
    size: letter landscape;
}

Instead of setting fixed page formats with a specified orientation it is also possible to set two length values. These then define page size and orientation.

@page {
    size: 4.25in 6.75in;
}

Named Pages

With named pages an element is able to create and appear on a special page that has a name. This name can be used as part of a page selector to attach additional style properties to all pages of that name.

To create a named page, an element receives the property with a page name as identifier.

table {
    page: pageName;
}

A page break will be inserted before an element that has the page property set. Another page break will be inserted for the next element that defines a different page name (or none) to ensure the Named Page only contains elements that specify its name.

To attach styles to a named page, the page name is added to the @page rule. The page name is not a pseudo-class like :first for example. There is a space between @page and the page name, not a colon.

@page pageName {
    size: letter landscape;
}

<section>
    <table class="landscape"> ... </table>
</section>

section {
    page: outerGroup;
}
.landscape {
    page: innerGroup;
}
/* Make all pages named 'outerGroup' lightblue */
@page :-ro-nth(n of outerGroup) {
    background-color: lightblue;
}
/* Make all pages named 'innerGoup' landscape */
@page :-ro-nth(n of innerGroup) {
    size: A4 landscape;
}

@page :-ro-nth(1 of pageName) {
    background-color: lightgrey;
}

Automatic Hyphenation

Automatic Hyphenation allows breaking words in a way appropriate for the language of the word.

To use Automatic Hyphenation two requirements must be met:

• The text to hyphenate requires a language set in the document.

• The language set for the hyphenated text is supported by PDFreactor (see Appendix for more information)

The lang attribute in HTML or the xml:lang attribute in XML allow defining a language for the document and on individual elements, in case they deviate from the document language.

<html lang="en">
    ...
</html>

Hyphenation is enabled or disabled via CSS with the property:

html {
    hyphens: auto;
}
p.noHyphenation {
    hyphens: none;
}

In addition it is possible to specify the number of minimum letters before or after which text can be broken within a word. This is done with the and properties.

The number of successive lines that all end with hyphenated words can be limited with the property. Instead of being automatically hyphenated, the word is then moved into the next line, if possible.

Widows & Orphans

By default, PDFreactor avoids widows and orphans by adding a page break before the paragraph. This behavior can be changed with the CSS properties and .

p {
    orphans: 2;
    widows: 2;
}

Changing the value to 1 will allow widows and orphans. Changing it to higher integer values will prevent even multiple line widows and orphans. (e.g.: orphans: 5 means that if the first 4 lines of a paragraph are the last 4 lines of a page these lines are considered an orphan.)

Customizing Line Breaks

By default, the rules for breaking words are defined by the Unicode StandardSee Unicode Standard Annex #14 - Unicode Line Breaking Algorithm - https://www.unicode.org/reports/tr14/ . In certain situations however, you may want to define specific break opportunities and forbid others. While this can be done using white-space and soft-hyphens, PDFreactor provides a more convenient way for general rules. The proprietary property -ro-line-break-opportunity allows to precisely define between which characters a break is allowed or forbidden.

Specifying this is done via Regular Expression (Regex), excluding lookaheads or lookbehinds. Though the syntax may look confusing to those that are unfamiliar with Regex, it allows to define any possible break opportunity. The property value is divided in up to three parts:

1. normal: This optional identifier specifies that the default rules still apply. Thus the existing rules are only extended instead of being completely overridden.

2. <whitelist>: These regex expression describe where break opportunities should be added.

3. <blacklist>: The blacklist is separated with a slash and describes where break opportunities should be removed. The blacklist is stronger than the whitelist and overrides it in the case of a conflict.

Both, whitelist and blacklist, describe the character matching using one or two strings. The first string describes the content that must come before, the second what must come after the break opportunity. The second string can be omitted, while the first string can be an empty string if it is not needed. In regex terms, the first string is a lookbehind, the second is a lookahead, hence the slightly reduced syntax.

A common use case of this property is when trying to break a file path or other technical strings where normal breaking rules are not applied.

Generated Text

To create generated text, set a String as value of the content property.

<div>This is a note.</div>

div::before {
    /* Adds the text "Note:" at the start of the element. */
    content: "Note:";

    padding-right: 0.1in;
    font-weight: bold;
}
div {
    border: 1px solid black;
    background-color: palegoldenrod;
    padding: 0.1in;
}

As a result, the <div> would look like this:

This is a note.

Sometimes it is necessary to add an explicit line break to generated text. To create such a line break, a "\A " (an escaped line break character followed by a space) needs to be added to the String and the property needs to be set to either pre, pre-wrap or pre-line.

div::before {
    content: "RealObjects\A PDFreactor";
    white-space: pre;
}

The result would look like this:

Generated Images

A generated image can be created with the image's URL set as value of the content property.

h1::before {
    content: url("https://mydomain/pictures/image.svg");
}

Counters

Counters can be used to count elements or pages and then add the value of the Counter to generated text.

A Counter needs to be defined either with the or the property. Its value is read with the counter() function as value of the content property.

A common use-case for Counters are numbered headings. The chapter heading of a document is intended to display a number in front of its text that increases with each chapter.

h1 {
    /* increases the counter "heading1" by 1 on each <h1> element */
    counter-increment: heading1 1;
}
h1::before {
    /* Adds the current value of "heading1" before the <h1> element's
       text as decimal number */
    content: counter(heading1, decimal)
}

Subchapter headings, work the same way, with a simple addition. The number of each subchapter is intended to be reset whenever a new chapter begins. To restart numbering, the counter-reset property is used.

h1 {
    /* resets the value of counter "heading2" to 0 on every  <h1> element */
    counter-reset: heading2 0;
}
h2 {
    counter-increment: heading2 1;
}

h2::before {
    /* Shows the current value of "heading1" and "heading2", separated by a
       generated text ".", the value of "heading2" is shown as lower-case
       letter */
    content: counter(heading1, decimal) "." counter(heading2, lower-alpha)
}

To define custom counter representations use the @counter-style rule. It is structured like this:

@counter-style <counter-style-name> {

    system:             <counter-system>;
    symbols:            <counter-symbols>;
    additive-symbols:   <additive-symbols>;
    negative:           <negative-symbol>;
    prefix:             <prefix>;
    suffix:             <suffix>;
    range:              <range>;
    pad:                <padding>;
    fallback:           <counter-style-name>;

}

To learn more on how to use the @counter-style rule, see the MDN Documentation.

Header, Footer & Page Side Boxes

It is possible to add Generated Content to a page within the page margin. The page margin is the space between the document content and the edges of a sheet. It is defined on a page using and the property.

Each page provides sixteen Page Margin Boxes that can display Generated Content much like a pseudo-element. To add Generated Content to a page, add a Page Margin Box declaration to an existing @page rule and set the Generated Content to the property as usual.

A Page Margin Box declaration consists of an "@" character followed by the name of the Page Margin Box.

@top-left {
    content: "RealObjects PDFreactor(R)";
}
@top-right {
    content: "copyright 2024 by RealObjects";
}

Running Elements

Running Elements are elements inside the document that are not rendered inside the document content but inside Page Margin Boxes.

They are useful whenever the content of a Page Margin Box needs to be more complex than Generated Content (e.g. a table) or parts of it need to be styled individually.

To create a Running Element, an element needs to be positioned as "running", using the running() function with an identifier for the element as argument. The function is set as value of the property. This removes the element from the document content.

To display a Running Element inside a Page Margin Box, set the element() function as value of the content property. The argument of the function is the same identifier used to in the running() function of the Running Element.

<body>
    <footer>...</footer>
    ...
</body>

footer {
    position: running(footerIdentifier);
}
@page {
    @bottom-center {
        content: element(footerIdentifier);
    }
}

The <footer> needs to be at the beginning of the HTML document to guarantee, that it will appear on every page of the document.

The reason for that is, that running elements stay anchored to the location they would appear in if they were not Running Elements.

The original position of the running element inside the document plays a key role when designing a document, it provides document designers with additional options.

First of all it is possible to have running elements of the same name, which makes it possible to change the content of a Page Margin Box over the course of the document.

<body>
    <header id="titlePageHeader">...</header>
    <header id="pageHeader">...</header>
    <!-- first page content -->
    ...
    <!-- second page content -->
    ...
</body>

#titlePageHeader, #pageHeader {
    position: running(headerIdentifier);
}
@page {
    @top-center {
        content: element(headerIdentifier);
    }
}

Second of all it is possible to have running elements appear for the first time later in the document than on the first page.

<body>
    ...
    <footer>...</footer>
</body>

footer {
    position: running(footerIdentifier);
}
@page {
    @bottom-center {
        content: element(footerIdentifier);
    }
}

It is possible that more than one Running Element of the same name would anchor on the same page. Sometimes, it may not be the first Running Element on a page that should be used for that page. For that case it is possible to add one of these identifiers as second argument to the element() function:

• start

  • Retrieves the latest Running Element of the name from previous pages.

  • If there is none, nothing is displayed.

• first

  • Retrieves the first Running Element of the name on the page.

  • If there is none, it falls back to the behavior of start.

  • This is the default behavior if no argument is given.

• last

  • Retrieves the last Running Element of the name on the page.

  • If there is none, it falls back to the behavior of start.

  • This keyword is useful in case a Running Element is displayed as footer throughout the document but the last page should receive a different Running Element, which is placed at the end of the document.

• first-except

  • If a Running Element of the name is on the page, nothing is displayed.

  • If there is none, it falls back to the behavior of start.

  • This keyword is useful on chapter title pages where the chapter name is already displayed.

Running Documents

In case does not suffice and are not an option, it is possible to use Running Documents inside Page Margin Boxes.

A Running Document is a String containing an HTML document or document fragment or a URL that references a document as argument of the xhtml() function.

/* document fragment */
content: xhtml("<table>…</table>");
/* complete document */
content: xhtml("<html><head>...</head><body>...</body></html>");
/* external document */
content: xhtml(url("header.html"));

The document is loaded independently inside the Page Margin Box but styles from the document are passed down to it. This can be an advantage as the same style is used throughout all documents. In some cases though this behavior is not desired as this style may break the layout of the document inside the Page Margin Box. To prevent passing down style the -ro-passdown-styles property is used.

<!--
@page {
    @top-center {
        content: xhtml("<table>...</table>");
    }
}
-->

Page Counters

To add page numbers to documents, Page Counters are used. Page Counters work like regular counters, but are defined on pages and accessed in page margin boxes.

The default Page Counter is named page and automatically defined in HTML documents.

@page {
    @bottom-right {
        content: counter(page);
    }
}

@page:first {
    counter-reset: page applicationValue("com/realobjects/pdfreactor/start-page-number");
}

Additionally there is the pages counter, which is always defined as the total number of pages of the laid out document.

content: "Page " counter(page) " of " counter(pages)

You can add an offset to the pages counter value (e.g. -1 to ignore the cover page) via the @-ro-preferences property .

Named Strings

Named Strings allow to store the text of an element and its as String for use in Page Margin Boxes.

A Named String is defined very similar to a Counter and is used in a similar way. To create a Named String the property is used, which requires an identifier and a definition of the contents of the String. To read a Named String the string() function is used as value of the content property.

h1 {
    string-set: headingString content(text);
}
@page {
    @top-left {
        content: string(headingString);
    }
}

The content of a named String is very flexible and can take a combination of Strings, counter() functions and Named String keywords.

/* Creates a Named String in the form of "Chapter [chapter number]: [chapter title]". */
h1 {
    string-set: headingString "Chapter " content(before) ": " content()
}
/* Retrieves the first letter of an address element, useful as part of a page header
    for a sorted list of addresses */
address {
    string-set: addressEntry content(first-letter);
}

When a Named String is set multiple times on the current page, the optional 2nd parameter of the function, defaulting to first, specifies which one to use:

• first: the first one

• last: the last one

• first-except: none, use empty string

• start: the first one, if it is at the beginning of the page

If there is none on the current page (or, in case of start, none at its beginning), the last one before is used. If there is none, either, the default is the empty string.

Cross-references

A Cross-reference is a piece of text that references another location in the document in order to establish a thematic relationship to that location.

Although it is perfectly possible to add such references by hand, this approach is prone to error when creating and modifying the document. After a change the numbering and page numbers might not match the numbering from when the cross-reference was first defined. The same could happen to the reference text if it includes the chapter title.

To always keep the reference up-to-date with the referenced location, CSS provides the target-counter() and target-text() functions to retrieve the exact numbering, title or page number of the referenced location.

...
<p>For more information <a href="#chapter">see</a>.
...
<h1 id="chapter">Cross-references</h1>
...

@page {
    @bottom-right {
        content: counter(page);
    }
}
h1 {
    counter-increment: chapterCounter;
}
h1::before {
    content: counter(chapterCounter, upper-roman);
}
a[href]::after {
    content: "Chapter " target-counter(attr(href), chapterCounter, upper-roman)
                " on page " target-counter(attr(href), page);
}

a[href]{
    content: target-text(attr(href), before) " "
        target-text(attr(href), content);
}

Footnotes

A footnote is a text note placed on the bottom of a page, a column or a region. It references a specific part of the main content of the document, giving further explanations or information about a citation. A footnote is marked by a defined symbol both in the main content of the page and in the footnote area at the bottom, to show which parts belong together.

For content that is required to have a footnote, the following style can be applied:

float: footnote;

<p>This is a CSS<span class="footnote">Cascading Style Sheet</span> generated footnote.</p>

.footnote {
    float: footnote;
}
@page {
    @footnote {
        border-top: solid black 1px;
    }
}

The pseudo-element ::-ro-footnote-area allows to select the footnote area of multi-column or region elements for styling.

.multiColumn {
    columns: 2;
}
.multiColumn::-ro-footnote-area {
    border-top: solid black 1px;
}

By defining a footnote, a footnote call is left behind in the main content. Its content and style can be influenced by the footnote-call pseudo-element.

For every footnote element, there is also a footnote-marker pseudo-element added. Usually this contains the same number or symbol as the footnote-call it belongs to.

.footnote::footnote-call {
    content: counter(footnote, decimal);
}
.footnote::footnote-marker {
    content: counter(footnote, decimal);
}

By default, the footnote counter is available and is automatically incremented for every element with the style:

float: footnote

@page {
    counter-reset: footnote;
}

Normally, footnotes are laid out as block elements, which means that they are stacked on top of each other. When having several short footnotes, it can make sense to place them next to each other, as if they were inline elements. This can be achieved by using the property, which can either be set to block or inline:

.footnote {
    float: footnote;
    footnote-display: inline;
}

Sidenotes

Sidenotes, also known as marginalia, are short notes that are put into the left or right page margin. They are similar to footnotes in function and usage, but have no influence on the layout.

In contrast to footnotes, a sidenote can be moved to the left or right. As the preferred side may depend on other factors like whether a page is a left page or the document's text direction (e.g. right-to-left), sidenotes are created by setting a CSS function with a parameter for the direction on the float property of the element that should become a sidenote.

As sidenotes are moved to the page margin, that margin should be increased to give them enough space. This can either be done directly by setting a margin on the page itself, or by setting a width on the sidenote area itself. The second option will be further explained in the Sidenote Area chapter below.

<p>This is the normal page content.<span class="sidenote">This is the sidenote</span></p>

.sidenote {
    float: -ro-sidenote(right);
}
@page {
    margin-right: 5cm;
}

By default, the sidenotes will be placed at the same height as the content surrounding it. The CSS property -ro-sidenote-align allows to specify a few other vertical positions that depend on the sidenote's context. For example, setting it to container-start will align the sidenote with the top of its surrounding paragraph.

.sidenote {
    float: -ro-sidenote(right);
    -ro-sidenote-align: container-start;
}

.sidenote {
    float: -ro-sidenote(right);
    -ro-sidenote-align: baseline strict;
}

.sidenote {
    float: -ro-sidenote(right);
    -ro-sidenote-align: container-start;
    -ro-sidenote-offset: 5mm;
}

<p>This is the normal page content.<span class="sidenote">This is the sidenote</span></p>

:root {
    /* Declare the sidenote counter for the whole document */
    counter-reset: sidenote;
}
.sidenote {
    float: -ro-sidenote(right);
    counter-increment: sidenote;
}
.sidenote::-ro-sidenote-call {
    content: "[" counter(sidenote) "]";
}
.sidenote::-ro-sidenote-marker {
    content: counter(sidenote) ")";
}
@page {
    margin-right: 5cm;
}

.sidenote {
    /* Prevent style inheritance */
    all: initial;
    float: -ro-sidenote(outside);
}

@page {
    margin-right: 2cm;
    @-ro-sidenote:right {
        /* Make area content twice as wide as margin-right of the page (4cm). */
        width: 200%;
        /* Add the right margin of the page to the area (2cm). */
        margin-right: 100%;
    }
}

@page {
    margin: 2cm;
    /* Styles that are the same for both page sides */
    @-ro-sidenote:outside {
        width: 3cm;
        background-color: #eee;
    }
}
@page:left {
    @-ro-sidenote:left {
        border-right: 1mm solid grey;
        margin-left: 2cm;
    }
}
@page:right {
    @-ro-sidenote:right {
        border-left: 1mm solid grey;
        margin-right: 2cm;
    }
}

@page {
    margin: 2cm;
    @-ro-sidenote:outside {
        width: 3cm;
        background-color: #eee;
        border-inline-end: 1mm solid grey;
        margin-inline-start: 2cm;
    }
}

Continuation Markers

When content is fragmented it can be helpful to show a hint that it is continued on the next page or a fragment is a continuation from a previous one. PDFreactor allows to specify such continuation markers.

The markers are generated content and as such they are addressed with proprietary pseudo-elements. The pseudo-element ::-ro-before-break creates markers at the bottom or before a break (e.g. "Continued on next page"), while ::-ro-after-break creates markers at the top or after the break. These continuation markers are only created if there is a next or previous fragment, i.e. the respective element is split.

In the current implementation, the continuation markers can only be applied on block elements (display: block). This means that when intending to apply them on a table, they must be used on a container element that wraps the table:

<div class="table">
    <table> ... </table>
</div>

div.table::-ro-before-break {
    content: "Continued on page " -ro-counter-offset(page, 1);
    text-align: center;
    font-weight: bold;
}
div.table::-ro-after-break {
    content: "Continuation from page " -ro-counter-offset(page, -1);
    text-align: center;
    font-weight: bold;
}

Reduce Table Width with Rotated Table Headers

is able to reduce the width of table headers with transforms.

The rotateTableHeaders() function transforms and rotates a table header, in order to reduce its width. If there is no table header, the first line is converted to one.

This function takes two parameters:

• table: The HTML node of the table

• params: An object of optional parameters

Adding Regions to Region Chains

Most block elements can be defined as a region. They are not required to be of the same size nor are they required to be the same node name.

To create a region from a block element, the property is used. It receives an identifier. A region chain contains all regions of the same identifier in document order. The identifier is also the name of the named flow these regions will display.

#region1, #region2 {
    -ro-flow-from: regionChainName;
}

PDFreactor lays out content into regions and breaks text and boxes where no space is left. The number of regions inside a region chain is limited by the number of associated Region elements though and it is possible that the content of a named flow occupies more space than is available inside the regions of a region chain. In that case content from the named flow overflows the last region inside the region chain.

Adding Content to a Named Flow

The -ro-flow-into property adds document content to a named flow. The content may consist of content from one or more elements. Content assigned to a named flow is not rendered at its position inside the document but inside one of the regions inside the region chain.

The property receives an identifier which is the name of the named flow the content belongs to. An optional keyword defines what part of the styled element should be taken into the named flow:

• element

  • Adds the entire element to the named flow.

  • If no keyword is given, this is the default behavior.

• content

  • Adds the element's content to the named flow.

<article>...</article>
<article>
    ...
    <section id="info">...</section>
</article>

article {
    -ro-flow-into: articleNamedFlowName;
}
section#info {
    -ro-flow-into: infoNamedFlowName;
}

Region Generated Content

A region element can have before and after just like any other element. This generated content is rendered above or below the region's content and is not moved to the next region due to lack of space. Instead the available space inside a region is reduced. If there is not enough space left, the region's content flows over.

Breaking Around Boxes

To manipulate the break behavior before and after boxes, the break-before and break-after properties are used. They provide keywords to force or avoid page, column and region breaks.

h1 {
    break-before: page;
}

h1 {
    break-before: right;
}

This style creates a page break before the h1 and moves it to the next page. In case this is a left page another page break is performed, to move it to a right page again.

h1, h2, h3, h4, h5, h6 {
    break-after: avoid;
}

Avoid Breaking Inside Boxes

To manipulate the break behavior inside a box, the property is used. It specifies whether breaking should be avoided inside the box or not.

div {
    break-inside: avoid;
}

Adaptive Page Breaks

is able to automatically add page breaks depending on the amount of space left below an element with the help of the applyAdaptivePageBreaks() function.

A possible use case is to prevent a new section from beginning at the bottom of a page.

The function also prevents large whitespaces that occur when in situations where only a couple of sentences from a previous section are followed by a page break as the next section begins.

The function takes two parameters:

• selector: (optional) The CSS selector for the elements that may require a new page break. Default value: "h1, h2"

• threshold: (optional) If an element is below this percentage of the page height, a page break is inserted. Default value: 67

PDF Page Boxes

Page boxes are used to specify the page geometry, especially in professional printing. PDFreactor supports the TrimBox, MediaBox, BleedBox, CropBox and ArtBox.

size: A4 portrait;

-ro-media-size: SRA4;

bleed: 3mm;

-ro-crop-size: media;

Printer Marks

Printer Marks are special pieces of information located outside of the actual print result. They are used to prove the correctness of the result in prepress printing and are placed outside the .

Cutting out the print result of the print sheet is done inside the bleed area. Trim and bleed marks indicate where this area starts and ends. Both types of marks are displayed as hairlines in the corner of the print sheet.

Registration marks show whether the printer's colors are aligned properly. They are printed as crosshair-shaped objects located on each side of the print sheet.

Color bars show if the colors of the print result meet the expected result. They consist of a variety of colors that can be checked individually.

The property is used to add crop, bleed and cross marks. The property sets the width of the mark lines, sets their color. The properties , and set the offset of the corresponding marks relative to the trim box. The property sets the offset of bleed marks relative to the bleed box. The properties and set the length of the corresponding marks and sets the size of registration marks.

marks: crop -ro-bleed cross;
-ro-marks-width: 1pt;
-ro-marks-color: red;

Setting one of the -ro-colorbar-* properties defines where a color bar is added to the document.

-ro-colorbar-bottom-left: gradient-tint;
-ro-colorbar-bottom-right: progressive-color;

Scaling Pixel Lengths

This configuration property adapts the "pixels per inch" value used for laying out the document, i.e. it only scales lengths set as px including such set via HTML attributes.

config.setPixelsPerInchShrinkToFit(true);

config.PixelsPerInchShrinkToFit = true;

$config["pixelsPerInchShrinkToFit"] = true;

config['pixelsPerInchShrinkToFit'] = True

config['pixelsPerInchShrinkToFit'] = true

config.pixelsPerInchShrinkToFit = true;

config.pixelsPerInchShrinkToFit = true;

{ "pixelsPerInchShrinkToFit": true }

The pixels per inch can also be specified manually.

Scaling Down Page Content

This property must be part of the @page rule affecting the first page:

@page {
    -ro-scale-content: auto;
}

Scaling Down Text

The proprietary value -ro-scale-down of the CSS property allows visually scaling down paragraphs that overflow at the end of lines to automatically make their text fit their width.

Contrary to normal text overflow styles, -ro-scale-down also works with multi-line text. It then applies the scaling to all lines, so that the whole text content is scaled down equally. However, only overflow in inline (i.e. horizontal) direction is taken into account to determine whether scaling needs to be applied, not overflow in block (i.e. vertical) direction.

This feature is especially useful if you want to force text whose length you can't control into a pre-defined container, such as forcing user-supplied text into an existing form field.

.scaleDown {
    /* Enable text scale down */
    text-overflow: -ro-scale-down;
    /* Make sure we only have a single line */
    white-space: nowrap;
    /* Don't scale vertically */
    align-content: stretch;
}

Fit Wide Tables

In cases where an HTML document contains tables that are very wide, usual shrinking strategies may not be appropriate since the table might have to be scaled down so much that it becomes illegible. In these cases you could use to convert the table into a compact version that displays the table columns as rows. The compactifyTable() function takes the following one or two arguments and automatically converts a wide table into a narrow variant.

• table — The HTML node of the table.

• params — An optional object of parameters. Refer to the Awesomizr API documentation for more information.

This conversion only works on uniform tables without any column or row spans.

Merge Mode Arrange

The syntax of page order is extended when setting the merge mode to MERGE_MODE_ARRANGE.

As usual, when the merge mode is selected PDFreactor requires one or more merge PDFs to be set (see ).

The merge documents specified with the array are numbered, beginning with one for the first PDF (when specifying a single document, it is also addressed with "1").

To select pages from a merge document, first use its number followed by a colon, which then is followed by the page order syntax described above. Note that the converted document can be addressed using 0:, however, this is not necessary, as it is used by default if no document is specified.

MergeSettings mergeSettings = new MergeSettings();
mergeSettings
    .setMergeDocuments(
        new Resource().setUri("https://www.myserver.com/insert1.pdf"),
        new Resource().setUri("https://www.myserver.com/insert2.pdf"))
    .setMode(MergeMode.ARRANGE);
config.setMergeSettings(mergeSettings);
config.setPageOrder("1,1:1,2..-1");

config.MergeSettings = new MergeSettings
{
    MergeDocuments = new List<Resource>
    {
        new Resource { Uri = "https://www.myserver.com/insert1.pdf" },
        new Resource { Uri = "https://www.myserver.com/insert2.pdf" }
    },
    Mode = MergeMode.ARRANGE
};
config.PageOrder = "1,1:1,2..-1";

$config["mergeSettings"] = array(
    "mergeDocuments" => [
        array("uri" => "https://www.myserver.com/insert1.pdf"),
        array("uri" => "https://www.myserver.com/insert2.pdf")
    ],
    "mode" => MergeMode::ARRANGE
);
$config["pageOrder"] = "1,1:1,2..-1";

config['mergeSettings'] = {
    'mergeDocuments' = [
        { 'uri': "https://www.myserver.com/insert1.pdf" },
        { 'uri': "https://www.myserver.com/insert2.pdf" }
    ],
    'mode': PDFreactor.MergeMode.ARRANGE
}
config['pageOrder'] = "1,1:1,2..-1"

config['mergeSettings'] = {
    mergeDocuments: [
        { uri: "https://www.myserver.com/insert1.pdf" },
        { uri: "https://www.myserver.com/insert2.pdf" }
    ],
    mode: PDFreactor::MergeMode::ARRANGE
}
config['pageOrder'] = "1,1:1,2..-1"

config.mergeSettings = {
    mergeDocuments: [
        { uri: "https://www.myserver.com/insert1.pdf" },
        { uri: "https://www.myserver.com/insert2.pdf" }
    ],
    mode: PDFreactor.MergeMode.ARRANGE
}
config.pageOrder = "1,1:1,2..-1";

config.mergeSettings = {
    mergeDocuments: [
        { uri: "https://www.myserver.com/insert1.pdf" },
        { uri: "https://www.myserver.com/insert2.pdf" }
    ],
    mode: PDFreactor.MergeMode.ARRANGE
}
config.pageOrder = "1,1:1,2..-1";

{ "mergeSettings": {
        "mergeDocuments": [
            { "uri": "https://www.myserver.com/insert1.pdf" },
            { "uri": "https://www.myserver.com/insert2.pdf" }
        ],
        "mode": "ARRANGE"
    }
    "pageOrder": "1,1:1,2..-1" 
}

The order shown above would be:

• "1" — Page 1 from the converted PDF.

• "1:1" — Page 1 from insert1.pdf.

• "2:A" — All Pages from insert2.pdf.

• "2..-1" — Pages 2 to the last page from the converted PDF.

• "1:2" — Page 2 from insert1.pdf.

Languages

PDFreactor supports Unicode and includes default fonts for various non-Latin languages. See for more information on the included fonts and on how to add additional fonts.

You can specify a language for the whole document either by using the HTML lang attribute or by specifying a default in the API:

<html lang="de-DE">

config.setDocumentDefaultLanguage("de-DE");

config.DocumentDefaultLanguage = "de-DE";

$config["documentDefaultLanguage"] = "de-DE";

config['documentDefaultLanguage'] = "de-DE"

config['documentDefaultLanguage'] = "de-DE"

config.documentDefaultLanguage = "de-DE";

config.documentDefaultLanguage = "de-DE";

{ "documentDefaultLanguage": "de-DE" }

The specified language will be used for automatic hyphenation of text and also conveys important information to screen readers when reading accessible PDFs. It is required to specify the document language when producing accessible PDFs, otherwise PDFreactor may use "en-US" as the default.

Counters and list item markers can also be displayed in numerous languages and writing systems. See for all supported styles.

lang attributes can also be used to change the language for parts of the document.

Right-to-Left

PDFreactor analyzes the document to handle both left-to-right and right-to-left text correctly.

The base direction of the document defaults to left-to-right. You can set it to right-to-left by specifying the dir attribute on the root element as in the following example:

<html dir="rtl">

You can also override the base direction specifically for certain elements via the property :

div.hebrew {
  direction: rtl;
}

You can override the implicit text direction by combining direction with the property :

span.forcertl {
  unicode-bidi: bidi-override;
  direction: ltr;
}

Text Direction Dependent Layouts

Using "logical" properties and values, as opposed to the common "physical" ones, allows layouts based on the text direction, instead of fixed "left" and "right" sides. They are mapped to physical sides based on the value of the direction property, which may be ltr (left-to-right, default) or rtl (right-to-left).

The following tables list the direction dependent logical properties and values as well as the resulting physical ones for both left-to-right and right-to-left direction:

Media Types

Media Queries are a CSS3 extension of media types. Media types allow to have styles that are only applied if the device or application displaying the document accepts the specified type. For example the following media rule will only be applied if the device accepts the media type print (which PDFreactor does):

@media print {
    p {
        background-color: transparent;
    }
}

If the styles of a certain media type have to be applied, but that media type is not accepted by PDFreactor (e.g. @media screen), the required media types can be set via API:

config.setMediaTypes("screen", "projection", "print");

config.MediaTypes = new List<string> { "screen", "projection", "print" }

$config["mediaTypes"] = array("screen", "projection", "print");

config['mediaTypes'] = [ "screen", "projection", "print" ]

config['mediaTypes'] = [ "screen", "projection", "print" ]

config.mediaTypes = [ "screen", "projection", "print" ];

config.mediaTypes = [ "screen", "projection", "print" ];

{ "mediaTypes": [ "screen", "projection", "print" ]}

This example sets the three media types screen, projection and print, thereby overriding PDFreactor's default types.

CSS that should only be used by PDFreactor can either be added by using the API or if they depend on the specific document you can use the proprietary media type -ro-pdfreactor.

For example the following rule disables the page background color only if the document is used by PDFreactor:

@media -ro-pdfreactor {
    @page {
        background-color: transparent;
    }
}

Media Features

Media Queries allow to make styles dependent on certain device features like width and height of the viewport. As they extend media types they may start with one type which can be followed by media features, each linked with the keyword and.

Media features describe certain device properties, are always enclosed by parentheses and resemble CSS properties. Additionally, some features may be prefixed with min- or max- in order to express "greater or equal to" and "less or equal to" relationships to their value.

@media print and (max-device-width: 1024px) {
    ...
}

The styles of this media rule are only applied if the device width is 1024px or less.

The device properties for conversions can be set using the API:

config.setMediaFeatureValues(new MediaFeatureValue()
    .setMediaFeature(MediaFeature.DEVICE_WIDTH)
    .setValue("1024px"));

config.MediaFeatureValues = new MediaFeatureValue
{
    MediaFeature = MediaFeature.DEVICE_WIDTH,
    Value = "1024px"
};

$config["mediaFeatureValues"] = array(
    array(
        "mediaFeature" => MediaFeature::DEVICE_WIDTH,
        "value" => "1024px"
    )
);

config['mediaFeatureValues'] = [{
    'mediaFeature': PDFreactor.MediaFeature.DEVICE_WIDTH,
    'value': "1024px"
}]

config['mediaFeatureValues'] = [{
    mediaFeature: PDFreactor::MediaFeature::DEVICE_WIDTH,
    value: "1024px"
}]

config.mediaFeatureValues = [{
    mediaFeature: PDFreactor.MediaFeature.DEVICE_WIDTH,
    value: "1024px"
}];

config.mediaFeatureValues = [{
    mediaFeature: PDFreactor.MediaFeature.DEVICE_WIDTH,
    value: "1024px"
}];

{ "mediaFeatureValues": [{
    "mediaFeature": "DEVICE_WIDTH",
    "value": "1024px"
}]}

The following table provides an overview of the supported media features. The default values can also be found in the PDFreactor API documentation.

Segmentation

Enabling segmentation allows PDFreactor to internally split conversions into multiple parts, drastically reducing the amount of memory required for large documents. The minimum document size for this to be noticeable depends on the complexity of the input document, but 5000 pages is a good estimate. This has no visible influence on the resulting PDF document, i.e. the edges of segments are not discernible. However there are some limitations:

• Regions are not supported.

• Shrink-to-Fit via pixelsPerInchShrinkToFit or -ro-scale-content is not supported.

• The pageOrder setting is not supported.

• The pages counter is not supported. This does not affect the "page" counter, other counters or named strings.

• Using the function outside of page margin boxes may cause unpredictable results. When it is absolutely necessary it is highly recommended to use on an ancestor element of the ones using the value.

• tfoot and thead elements must be placed before the tbody or tr elements of the same table. (If the document is not too large this can be corrected via JavaScript.)

• All style elements must be in the header.

• Due to the total amount of pages being unknown during the conversion of any segment but the last, log output and progress monitoring cannot estimate the progress of the conversion.

• For the CSS functions target-counter and target-text to be able to access information from previous segments the property must be used. It is also important that ID attributes are unique through the entire document.

• , when enabled, is run in a preprocessing step with no access to any layout information and increases memory consumption to some extend.

If these restrictions are acceptable, the feature can be enabled in the PDFreactor configuration:

config.setSegmentationSettings(new SegmentationSettings()
    .setEnabled(true));

config.SegmentationSettings = new SegmentationSettings
{
    Enabled = true
};

$config["segmentationSettings"] = array(
    "enabled" => true
);

config['segmentationSettings'] = {
    'enabled': True
}

config['segmentationSettings'] = {
    enabled: true
}

config.segmentationSettings = {
    enabled: true
};

config.segmentationSettings = {
    enabled: true
};

{ "segmentationSettings": {
    "enabled": true
}}

Some optional functionalities increase the amount of memory required, due to data accumulating over the course of the entire conversion. These include links, bookmarks, tagging and logging at levels more verbose than info.

Fast Tables

Very large tables have a significant impact on performance. Tables that have simple structures and only basic sets of styles can be declared as fast tables, providing significantly better performance and lower memory requirements at the cost of the following restrictions:

• Cell content is handled as a single line of text with uniform style and no influence on the table layout. If there is too much content, it will overflow.

• Styles applied to the cells of the first two body rows are used for the rest of the table's content. Applying different styles to the second row allows alternating even/odd styles. Styles set on the child nodes of cells or other table body rows are ignored. Vertical borders (i.e. border-right) can not be alternated between rows.

• The structure is homogeneous, with all body rows having the same height and the cells of the first row (header or body) defining the widths of their columns. Widths are taken from style only, without measuring content. Column or row spans are not supported. Missing row elements and other incorrect structuring will lead to unexpected results.

• Supported styles on cells are: , , , , , , , , , , , , border-right, border-bottom, and related shorthands.

• Supported styles on rows are: , and related shorthands.

• Supported styles on col elements are: , and related shorthands.

• The cell borders are created by using the border-right and border-bottom styles, creating a grid between the cells, similar to the effect of border-collapse: collapse. The borders at the table edges are created from the styles of the table element.

  Table footer cells are an exception as they use their border-top styles (instead of border-bottom) to create the horizontal border between body and footer cells.

• Repeating table header and footer groups are limited to one row each. Those are styled independently from the table body.

• All lengths must be absolute, except for the widths of columns which also support percentages.

• The style set on the table element is also used for all cells. The property is not supported. BiDi processing is applied to the text when necessary as usual. Font fallback is done based on the first character of each cell only. Specifying a font with sufficient glyphs is recommended.

• The property only supports the values top, middle and bottom, all others defaulting to top. This makes top the default behavior, except for HTML based tables, which default to middle as usual. does not support the values justify or justify-all.

• PDF tagging functionality has no access to the content of such tables. By default fast tables are marked as artifacts, making them not accessible.

If these restrictions are acceptable, the feature can be enabled by setting the style : -ro-fast-table on table elements. The style can be applied selectively, to affect only specific tables of the document.

Recommendation for Large Documents

The convertAsync method should be used. See and for details.

Comments

It is possible to add PDF comments to the document using the addComments configuration property like this:

config.setAddComments(true);

config.AddComments = true;

$config["addComments"] = true;

config['addComments'] = True

config['addComments'] = true

config.addComments = true;

config.addComments = true;

{ "addComments": true }

Depending on how the comment information is stored in your HTML source document, there are several style rules that can be applied. The most common use-cases are to either create a comment from an empty element (where any information is stored in its attributes) or to create a comment from a non-empty element (where the content is the text encompassed by the element):

<span class="comment" text="My Comment."></span>

span.comment {
    -ro-comment-content: attr(text);
}

<span class="comment">This text is commented</span>

span.comment {
    -ro-comment-content: content();
}

There are different styles to visualize a comment in the PDF:

• note: Creates a small icon. This is the default style for all comments.

• invisible: Does not create any visual effects.

• highlight: Highlights the background of a section of text.

• underline: Underlines a section of text with a straight line.

• strikeout: Strikes out a section of text.

• squiggly: Underlines a section of text with a squiggly line.

The comment styles highlight, underline, strikeout and squiggly are only applicable to comments that encompass a section of text.

The following example demonstrates how to style a simple comment.

<span class="comment">This is a styled comment</span>

span.comment {
    -ro-comment-content: content();
    -ro-comment-style: underline;
}

Comments can be customized further by using a variety of style rules. Besides content and style, you can also customize the following properties:

• Title: The title of the comment. In some cases, this is also used for the author. Use the CSS property to specify the title.

• Color: The color of the comment. The default value for the color depends on the comment style chosen. Use the CSS property to set a color.

• Date: The date of the comment. When no date is specified, the current date is used. Use the CSS property to set the date.

• Date Format: The format of the date you specified. The syntax is identical to Java's SimpleDateFormat SimpleDateFormat API documentation: https://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.html . Use the CSS property to specify a date format for the comment's date.

• Position: The position of the comment icon (only applicable for the comment style note). Use the CSS property to specify a position for the comment's note icon.

• Initial state: The initial state of the comment, i.e. whether the comment should be open or closed when the PDF is opened in a viewer. Use the CSS property to specify the initial state of the comment bubbles. The state can be either open or closed with the latter being the default value.

The following sample shows how to customize all of the aforementioned properties.

.comment {
    /* Content: get the content of the comment from the text content of the element */
    -ro-comment-content: content();
    /* Title: get the title from the "author" attribute of the element */
    -ro-comment-title: attr(author);
    /* Style: set the comment style to "note" */
    -ro-comment-style: note;
    /* Color: specify a color for the comment */
    -ro-comment-color: steelblue;
    /* Date: get the date from the "date" attribute of the element */
    -ro-comment-date: attr(date);
    /* Date Format: specify a custom date format */
    -ro-comment-dateformat: "yyyy/dd/MM HH:mm:ss";
    /* Position: shift the comment icon to the right side of the page */
    -ro-comment-position: page-right;
    /* Initial state: open comment bubbles when the PDF is opened */
    -ro-comment-state: open;
    /* additional styles */
}

Please see the documentation of the individual CSS properties for more information.

commentstart {
    /* some customizations */
    -ro-comment-content: attr(text);
    -ro-comment-title: attr(author);
    -ro-comment-style: highlight;

    /* define the comment start element */
    -ro-comment-start: attr(uid)
}

commentend {
    /* define the comment end element */
    -ro-comment-end: attr(uid);
}

Change Bars

Especially when marking only a single word or even less, the usual highlighting styles may not be enough. In such cases, PDFreactor's Change Bars can help to draw attention. A change bar is simply a colored line next to the content, on the same height as the element that enabled it.

The proprietary property -ro-change-bar-color enables them when set to a color.

ins {
    -ro-change-bar-color: yellowgreen;
}

del {
    -ro-change-bar-color: orangered;
}

To prevent different kinds (i.e. colors) of change bars from overlapping, each change bar can be assigned a different offset from the page content edge, by setting -ro-change-bar-offset.

Alternatively, it is also possible to move a change bar to the other page side altogether by using -ro-change-bar-align. This property defines where the change bars are positioned. By default, the bars are positioned in the left (or right) page margin area. If they come from a multi-column element, however, it makes sense to position them next to the columns.

.multi-column ins {
    -ro-change-bar-color: yellowgreen;
    -ro-change-bar-width: thick;
    -ro-change-bar-align: outside column;
}

In the sample above, the bars will be placed next the respective column, while the side of the column depends on the side of the page. With outside meaning right side for right pages and left side for left pages. There is another special setting best used for multi-columns with only two columns. The value distribute-column is combined with page and distributes the change bars on the left and the right side of the page, depending on which side is closer to the column in which the change bar originates.

.multi-column ins {
    -ro-change-bar-color: yellowgreen;
    -ro-change-bar-align: outside distribute-column page;
}

Lastly, it is also possible to block change bars next to certain elements. This is done via the CSS property -ro-change-bar-exclusion. By setting it to all, the painting of every change bar on the same vertical position as the respective element is blocked.

By giving change bars specific names via the CSS property -ro-change-bar-name, the exclusion can also be applied to selected change bars only.

ins {
    -ro-change-bar-color: yellowgreen;
    -ro-change-bar-align: outside distribute-column page;
    -ro-change-bar-name: insertion;
}
.exclude {
    /* Block two named change bars next to elements with this class */
    -ro-change-bar-exclusion: insertion, deletion;
}

Note that different change bars may share the same name, which allows to exclude them by groups.

Roles

The role HTML attribute is used to convey semantic meaning of document components to screen readers. Roles are mapped to PDF tag types as follows: