PDFreactor Web Service Configuration on Windows

On Windows systems the PDFreactor Web Service is started with the Local Service account by default.

When the Web Service is started using this account, it can only access files from the local file system that the Local Service account is allowed to access. For example, files from the user's home directory cannot be read on most systems. The Web Service may or may not be able to read files from other locations on the disk depending on the system configuration. If you need the Web Service to be able to access a particular file or folder on the disk, add the Local Service user to the list of users that can access this file or folder, and enable read permissions for this user.

In production environments, you may wish to start the PDFreactor Web Service with its own distinct user account.

PDFreactor Web Service Configuration on Linux / Unix

On Linux and Unix systems the PDFreactor Web Service has the same permissions as the user that started it.

Using PDFreactor in a Servlet

When used in a Servlet to generate a PDF that is returned to the client (e.g. a browser) PDFreactor can write directly to the ServletOutputStream:

ServletOutputStream out = response.getOutputStream();
response.setContentType("application/pdf");
pdfReactor.convert(config, out);
out.close();

Logging

PDFreactor uses the Java Logging API to output information about its progress. A simple console logger can be created like this:

Logger pdfReactorLogger = Logger.getAnonymousLogger();
pdfReactorLogger.setLevel(Level.INFO);
pdfReactorLogger.addHandler(new DefaultHandler());
config.setLogger(pdfReactorLogger);

Additionally, you can append the log to the generated PDF by using the method setAppendLog like this:

config.setAppendLog(true);

config.setLogLevel(PDFreactor.LogLevel.WARN);

OSGi Support

PDFreactor provides support for OSGi out of the box. The Manifest of the self-contained variant of PDFreactor (pdfreactor.jar) includes all entries required to deploy it as a bundle in your OSGi environment. Only the self-contained version of PDFreactor is OSGi compatible. The non-self-contained variant of PDFreactor ("pdfreactorcore.jar" and associated libraries) does not contain appropriate Manifest entries. Keep in mind that overwriting, removing or modifying the Manifest of pdfreactor.jar may break OSGi compatibility.

Asynchronous Conversions

The PDFreactor Web Service can convert documents asynchronously, meaning that the client is not required to keep an open HTTP connection to the server until the conversion is finished. While this is usually negligible when converting small documents, synchronous conversions may be very detrimental to the user experience when converting large or complex documents.

// sync
Result result = pdfReactor.convert(config);
// async
String id = pdfReactor.convertAsync(config);

Progress progress = pdfReactor.getProgress(id);

Result result = pdfReactor.getDocument(id);

config.setKeepDocument(true);

pdfReactor.deleteDocument(id);

Using the REST API

The REST API provides application- and language-neutral access to the PDFreactor Web Service. To use a RESTful resource, your application has to open an HTTP connection to the appropriate URL. While the RESTful URLs are not identical to the appropriate wrapper methods, the names are recognizable (see for a comparison).

The RESTful PDFreactor Web Service can be reached via the URL http://localhost:9423/service/rest, unless otherwise deployed or configured. The WADL Web Application Description Language is available under http://localhost:9423/service/rest?_wadl.

RESTful resources respond with an appropriate HTTP status code. Please see the REST API documentation for detailed information. The following table gives a comprehensive overview of all available RESTful resources:

http://localhost:9423/service/rest/convert

<ns:configuration xml:ns="http://webservice.pdfreactor.realobjects.com/">
    <document>http://www.realobjects.com</document>
</ns:configuration>

{
    "document": "http://www.realobjects.com"
}

http://localhost:9423/service/rest/document/1234

http://localhost:9423/service/rest/document/1234.json

http://localhost:9423/service/rest/document/1234.pdf

Asset Packages

Instead of using a simple configuration to convert an external document, the REST service also accepts an asset package in ZIP format. This package must have a configuration.xml or configuration.json file in its root directory. The content of this configuration file is a normal configuration in XML or JSON format, except that the document is specified as a URL relative to it. All other resources required by the document can also be placed in the asset package and can be linked relatively to the document.

{
    "document": "input.html",
    "userStyleSheets": [
        {
            "uri": "styles/common.css"
        }
    ]
}

myPackage.zip
|- configuration.json
|- input.html
|- styles
   |- common.css

curl -X POST -H "Cache-Control: no-cache" -H "Content-Type: application/zip" --data-binary @myPackage.zip "http://localhost:9423/service/rest/convert.pdf" > result.pdf

Using a Wrapper

PDFreactor can also be easily integrated in your web apps using one of the wrappers APIs, i.e. PHP, .NET, Python, Perl, Ruby, Java, JavaScript, Node.js or Python Command Line. This has to be used in conjunction with the PDFreactor Web Service which is run by a Jetty web application server (see chapter ).

See also The PDFreactor Web Service for information on how to start the service.

include("/path/to/PDFreactor.class.php");

<?php
include("../PDFreactor.class.php");
$pdfReactor = new PDFreactor();
$config = array("document" => "http://www.pdfreactor.com");

try {
    $result = $pdfReactor->convertAsBinary($config);
    header("Content-Type: application/pdf");
    echo $result;
} catch (Exception $e) {
    print "Content-type: text/html\n\n"
    puts "<h1>Error During Rendering</h1>"
    puts "<h2>.$e->getMessage().</h2>"
}
?>

PDFreactor pdfReactor = new PDFreactor();
Configuration config = new Configuration();
config.Document = "http://www.pdfreactor.com/";

try
{
    byte[] pdf = pdfReactor.ConvertAsBinary(config);
}
catch (PDFreactorWebserviceException e)
{
    // ...
}

<%@ Page Language="C#" Debug="false" %>
<%@ import namespace="RealObjects.PDFreactor.Webservice.Client" %>
<%
PDFreactor pdfReactor = new PDFreactor();
RealObjects.PDFreactor.Webservice.Client.Configuration config =
            new RealObjects.PDFreactor.Webservice.Client.Configuration();
config.Document = "http://www.pdfreactor.com/";

try
{
    byte[] result = pdfReactor.ConvertAsBinary(config);

    Response.ContentType = "application/pdf";
    Response.BinaryWrite(result);
}
catch (PDFreactorWebserviceException e)
{
    Result result = e.Result;
    Response.Write("<h1>Error During Rendering</h1>>");
    Response.Write("<h2>"+result.Error+"</h2>");
}
%>

import sys
sys.path.append("path/to/PDFreactor.py/")
from PDFreactor import *

pdfReactor = PDFreactor()
config = { "document": "http://www.pdfreactor.com" }

try:
    result = pdfReactor.convertAsBinary(config)

    # Used to prevent newlines are converted to Windows newlines (\n --> \r\n)
    # when using Python on Windows systems
    if sys.platform == "win32":
        import os, msvcrt
        msvcrt.setmode(sys.stdout.fileno(), os.O_BINARY)

    print "Content-Type: application/pdf\n"
    sys.stdout.write(result)
except Exception as e:
    print "Content-Type: text/html\n"
    print "<h1>Error During Rendering</h1>"
    print "<h2>"+str(e)+"</h2>"

if sys.platform == "win32":
    import os, msvcrt
    msvcrt.setmode(sys.stdout.fileno(), os.O_BINARY)
    print "Content-Type: application/pdf\n"
    sys.stdout.write(result.docuent)

require "PDFreactor.pm";

my $pdfReactor = PDFreactor -> new();
$config = { "document" => "http://www.pdfreactor.com" };

eval {
    $result = $pdfReactor -> convertAsBinary($config);

    print "Content-type: application/pdf\n\n";
    binmode(STDOUT);
    print $result;
} || do {
    my $e = $@;

    print "Content-type: text/html\n\n";
    print "<h1>Error During Rendering</h1>";
    print "<h2>"+$e+"</h2>";
};

binmode(STDOUT);

require 'PDFreactor.rb'

pdfReactor = PDFreactor.new()
config = { document: "http://www.pdfreactor.com/" }

begin
    result = pdfReactor.convertAsBinary(config);

    print "Content-type: application/pdf\n\n"
    $stdout.binmode
    print result
rescue Exception => e
    print "Content-type: text/html\n\n"
    puts "<h1>Error During Rendering</h1>"
    puts "<h2>#{e}</h2>"
end

$stdout.binmode

PDFreactor pdfReactor = new PDFreactor();
Configuration config = new Configuration();
config.setDocument("http://www.pdfreactor.com/");

try {
    byte[] result = pdfReactor.convertAsBinary(config);

    // handle the pdf
} catch (PDFreactorWebserviceException e) {
    Result result = e.getResult();
    System.out.println(e.getError());
} catch (Exception e) {
}

<script src="PDFreactor.js" />

const PDFreactor = require('PDFreactor.js');

// not possible:
var result = pdfReactor.convert(config);
// correct usage:
pdfReactor.convert(config, successHandler, errorHandler);
            

pdfReactor = new PDFreactor();
config = { document: "http://www.pdfreactor.com/" };
pdfReactor.convert(config, function(result) {
    var pdf = result.document;
    // handle the PDF
}, function(e) {
    console.log(e);
});

python pdfreactor.py -i input.html

pdfreactor.exe -i input.html

python pdfreactor.py -i /directory/documents

python pdfreactor.py -i /directory/documents/test*.html

Custom Headers and Cookies

In certain situations it may be necessary to set custom headers and cookies to the connection from the wrapper to the PDFreactor Web Service. This can be done with the headers and cookies properties of the PDFreactor object.

pdfReactor.headers['my-header'] = 'my-header-value';
pdfReactor.cookies['my-cookie'] = 'my-cookie-value'; // Node.js only

$pdfReactor->headers["my-header"] = "my-header-value";
$pdfReactor->cookies["my-cookie"] = "my-cookie-value";

pdfReactor.headers["my-header"] = "my-header-value"
pdfReactor.cookies["my-cookie"] = "my-cookie-value"

pdfReactor.headers["my-header"] = "my-header-value"
pdfReactor.cookies["my-cookie"] = "my-cookie-value"

$pdfReactor->{headers}->{'my-header'} = 'my-header-value';
$pdfReactor->{cookies}->{'my-cookie'} = 'my-cookie-value';

pdfReactor.getHeaders().put('my-header', 'my-header-value');
pdfReactor.getCookies().put('my-cookie', 'my-cookie-value');

pdfReactor.Headers.Add('my-header', 'my-header-value');
pdfReactor.Cookies.Add('my-cookie', 'my-cookie-value');

Web Service Configuration

The PDFreactor Web Service can be configured in several ways. Most commonly, as described in the chapter , you may want to increase the amount of memory available.

…
jetty.http.port=9423
…

…
jetty.http.host=localhost
…

$pdfReactor = new PDFreactor("http://myServer:9423/service/rest");

PDFreactor pdfReactor = new PDFreactor("http://myServer:9423/service/rest");

pdfReactor = PDFreactor("http://myServer:9423/service/rest");

my $pdfReactor = PDFreactor -> new("http://myServer:9423/service/rest");

pdfReactor = PDFreactor.new("http://myServer:9423/service/rest");

PDFreactor pdfReactor = new PDFreactor("http://myServer:9423/service/rest");

pdfReactor = new PDFreactor("http://myServer:9423/service/rest");

python pdfreactor.py -u http://myServer:9423/service/rest -i input.html

Logging

The logging mechanism for the APIs that use the web service is different from the logging mechanism of the Java API. Here, the Configuration object of PDFreactor has two additional properties log and error which are available in the Result object after the conversion process to retrieve the log or any errors which may have occurred during the conversion, respectively.

Another way of retrieving the log is using the property appendLog. This will append the log to the generated PDF you have both the generated PDF and the log in one document.

Additionally, the entire log output of the Jetty application server is written into log files located in the PDFreactor/jetty/logs directory.

$config = array(
    logLevel => LogLevel::DEBUG,
    appendLog => true
);

Configuration config = new Configuration();
config.LogLevel = LogLevel.DEBUG;
config.AppendLog = true;

config = {
    'logLevel': PDFreactor.LogLevel.DEBUG,
    'appendLog': True
}

$config = {
    'logLevel' => PDFreactor::LogLevel -> DEBUG,
    'appendLog' => true
}

config = {
    logLevel: PDFreactor::LogLevel::DEBUG,
    appendLog: true
}

Configuration config = new Configuration();
config.setLogLevel(LogLevel.DEBUG);
config.setAppendLog(true);

config = {
    logLevel: PDFreactor.LogLevel.DEBUG,
    appendLog: true
}

python pdfreactor.py --logLevel DEBUG --appendLog -i input.html

Load Balancing

In high availability and high performance environments it is common to run multiple PDFreactor Web Services behind a load balancer.

When doing synchronous conversions, no additional configuration or settings are required since the request to the web service is completely stateless. When doing asynchronous conversions on the other hand, you have to make sure that all relevant requests are routed to the same web service by the load balancer. This can usually be achieved by setting a sticky cookie. Please refer to the manual of the load balancer on how exactly to handle sticky sessions. When using a wrapper, cookies can be set using the cookies property of the PDFreactor instance (see )

Server Parameters

Additional configuration options for the server can be specified for the PDFreactor Web Service. These are either parameters the client should not or cannot influence, and they affect all conversions.

The following parameters can be configured:

• licenseKeyPath Specifies a file system path to the directory where the licensekey.txt file is located.

• docTempDir This parameter specifies the location of the Web Service's temporary folder which is used to store asynchronously converted documents. The pre-configured location is the pdfreactor/doctemp directory in the PDFreactor/jetty directory.

• fontCacheDir This specifies the location of the PDFreactor font cache used by the Web Service. The pre-configured location is the pdfreactor/fontcache directory in the PDFreactor/jetty directory.

• disableDocTemp If set to true, the Web Service will not use a temp folder. This also means that asynchronous conversions are not available. Synchronous conversions will be done in-memory, so make sure that the Web Service has sufficient amounts of memory available.

• disableFontCache If set to true, the Web Service will not use a file-based font cache. Generally, this is not recommended since the font cache will then have to be created for every conversion which is likely to have a significant performance impact. The default value is false.

• disableFontRegistration If set to true, font registration is disabled and any existing font cache will be ignored and the font directories will be scanned for font information. The default value is false.

• disableSystemFonts If set to true, PDFreactor will neither scan for nor use system fonts that are installed on the server. Only fonts specified via CSS and via the server parameter fontDirs as well as PDFreactor internal fonts will be used.

• fontCacheDir This specifies the directory of the font cache, which will be created by PDFreactor. If no path is specified, the font cache will be created in PDFreactor/jetty/pdfreactor/fontcache.

• fontDirs This parameter takes a colon or semicolon separated list of directories that PDFreactor should scan for fonts.

• threadPoolSize This parameter determines the number of parallel conversions that can be performed by the PDFreactor Web Service. Please note that while there is no maximum value for this, only a thread pool size that is lower as or equal to the system's maximum amount of threads will increase performance when converting documents in parallel. The default value is calculated from the system's number of processors.

• docTempRetentionPeriod Asynchronous conversions create temporary files on the server, which are automatically deleted when they are read once. If results of asynchronous conversions are not accessed, these files remain on the server and are deleted after a certain amount of days equal to this parameter. The default value is 5 (days).

• serverLogMode This parameter configures the log mode of the server. If set to bulk (the default value), the entire log output of a PDF conversion is dumped after the conversion is finished. This can also be set to live which outputs log entries directly. However if there are multiple conversions in parallel, log entries from other conversions may be written out at the same time, so there is no guarantee that you will receive a coherent log of a single conversion (contrary to bulk). The mode off disables the server-side logging of all conversions.

• conversionTimeout Specifies a timeout in seconds after which conversions automatically terminate. Specifying the value "0" means that there is no timeout. By default, no timeout is configured.

• callbackTimeout When clients specify callbacks without a timeout, this value will be used as a default timeout (in seconds) for connections to the callback URL. The default value is 30 (seconds).

• callbackMaxTimeout Callback timeouts with a negative or zero value are treated as an infinite timeout. If infinite timeouts are undesirable for your server, you can limit it to this value (in seconds). By default, no maximum timeout is configured.

• assetPackageMaxSize Limits the maximum size of the asset package (in bytes). A value of 0 or a negative value indicates that there is no size limit. By default, no maximum size is configured.

• assetPackageFiles This parameter limits the maximum number of files that an asset package may contain. A value of 0 or a negative value indicates that there is no file limit. The default value is 1000.

• apiKeys This parameter specifies a comma separated list of strings that are used as API keys. See for more information.

• apiKeysPath Similar to apiKeys, but instead of a comma separated list it specifies the path to the file apikeys.json containing a JSON object with API keys as keys and a description as value. See for more information.

• adminKey This parameter specifies a key for privileged access to the service.

• adminKeyPath Similar to adminKey, but specifies the path to the file adminkey.txt which contains the admin key.

These server parameters can be configured in various ways:

com.realobjects.pdfreactor.webservice.parameterName=parameterValue

-Dcom.realobjects.pdfreactor.webservice.parameterName=parameterValue

<Call name="setInitParameter">
    <Arg>com.realobjects.pdfreactor.webservice.parameterName</Arg>
    <Arg>parameterValue</Arg>
</Call>

export PDFREACTOR_PARAMETERNAME=parameterValue

parameterName=parameterValue

Callbacks

When performing asynchronous conversions, you usually have to regularly poll the progress of these conversions to determine when they are finished. As an alternative, you could also use callbacks which will notify you automatically about certain steps of the conversion by performing an HTTP POST request to a specified URL. The posted data is either in JSON, XML or plain text format, depending on the content type that is specified for the callback. Some callbacks return the same data model as if you had called the appropriate API methods. If the specified format is plain text, the data consists of a small string containing only a minimum amount of information.

The following callback types are available:

If you want to be notified once the conversion is done, this example demonstrates how to add a simple "ping" that just posts the document ID of the finished conversion to your serve.

config.setCallbacks(new Callback()
    .setUrl("http://myServer/myEndpoint1")
    .setType(CallbackType.FINISH)
    .setContentType(ContentType.TEXT));

The next example demonstrates how to add a PROGRESS callback that will be called every 2 seconds until the conversion is finished. The posted data will be in JSON format.

config.setCallbacks(new Callback()
    .setUrl("http://myServer/myEndpoint2")
    .setType(CallbackType.PROGRESS)
    .setContentType(ContentType.JSON)
    .setInterval(2));

Restricting Client Access

When your PDFreactor service is accessible for a large number of clients or is located in a public cloud, it may be desireable to retrict access to it so that only authorized clients can use the API. This can be done with so called "API keys". API keys are arbitrary strings that clients must send with each request, otherwise the request will be rejected.

API keys can be configured via the server parameters (see ) apiKeys or apiKeysPath. The first parameter specifies a comma separated list of API keys. The latter one specifies the path to a file apikeys.json. That file contains a single JSON object with API keys as keys and a description of the API key as value. This is useful if you use lots of different API keys for different clients and want to have an onverview of which API key is used for which client.

To gain access, clients must always send a valid API key with each request. When usine one of the wrappers, an API key can be conveniently set like this (Java example):

pdfReactor.setApiKey("myApiKey");

When using the REST API directly, the API key must always be included in the URL as a query parameter:

/rest/version?apiKey=myApiKey

Monitoring

Server administrators may wish to monitor the PDFreactor Web Service and gain access to conversion statistics or server specifics. This can be done via the monitoring REST API.

What API Method Should I Use?

When using PDFreactor Web Service clients, you have several convert API methods (or RESTful resources) at your disposal. Depending on the use case, some API methods are more efficient than others.

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 setLicenseKey method of the Configuration class.

Example:

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

config.setErrorPolicies(ErrorPolicy.LICENSE)

Setting the License Key in the Web Service

For integrators that use the PDFreactor Web Service with either one of the wrapper APIs or the REST API, it may be useful to not set the license key in their client-side integration. In this case, you can just copy the licensekey.txt file to the PDFreactor/jetty/lib/ext directory (where the pdfreactor.jar and the pdfreactor-webservice.jar files are located). PDFreactor will automatically scan for a license key file in that location and use it if one is found.

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);

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

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);

After the conversion, you can access and analyze a log containing all missing resources using the method getMissingResources. 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.

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);

A log containing all connections or connection attempts can be accessed after the conversion via the getConnections method. 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.

Images

PDFreactor has support for the image formats PNG, JPEG, GIF, TIFF, BMP, ICU, CUR, PAM, PBM, PGM, PPM as wells as limited support for PSD, DCX, ICNS and RGBE.

Images are embedded by PDFreactor "as-is", whenever possible, unless the propeties 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: -ro-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, you can select an attribute of this element. The value of this attribute must always be of the type URI Uniform Resource Identifier (http://www.w3.org/Addressing/) and is used to load the image.

SVG

PDFreactor supports the following SVG types: SVG and SVGZ. PDFreactor automatically converts SVG Scalable Vector Graphics (http://www.w3.org/Graphics/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>

The style -ro-rasterization: avoid disables the aforementioned SVG features to avoid having to rasterize the image.

The property configures the resolution of the rasterization. The default value is 2, meaning twice the default CSS resolution of 96dpi. Accepted values are all positive integers. Higher resolution factors increase the quality of the image, but also increase the conversion time and the size of the output documents.

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

Barcode

PDFreactor supports displaying barcodes in documents using the Barcode XML format from Barcode4J:

<p><b>EAN-13:</b></p>
<barcode:barcode xmlns:barcode="http://barcode4j.krysalis.org/ns"
    message="123456789012">
    <barcode:ean-13/>
</barcode:barcode>
<br>sometext.......

MathML

PDFreactor supports displaying MathML Mathematical Markup Language (http://www.w3.org/Math/) in documents using the MathML XML format.

<math:math mode="display" xmlns:math="http://www.w3.org/1998/Math/MathML">
  <math:mrow>
    <math:munderover>
      <math:mo>&#x222B;</math:mo>
      <math:mn>1</math:mn>
      <math:mi>x</math:mi>
    </math:munderover>
    <math:mfrac>
      <math:mi>dt</math:mi>
      <math:mi>t</math:mi>
    </math:mfrac>
  </math:mrow>
</math:math>
        

QR Code

PDFreactor supports displaying QR codes Quick Response Code (http://www.denso-wave.com/qrcode/index-e.html) in documents using the following style:

.qrcode {
    -ro-replacedelement: qrcode;
}

If the replaced element is applied to an HTML link, the reference URL (resolved against the base URI) is used as the content of the QR code, e.g.:

<a href="http://www.pdfreactor.com" class="qrcode"></a>

In any other case the text content of the element is used, e.g.:

<span class="qrcode">
BEGIN:VCARD
VERSION:2.1
N:Doe
FN:John
TEL:+1-555-123-456
TEL;FAX:+1-555-123-457
EMAIL:johndoe@johndoe.com
URL:http://www.johndoe.com
END:VCARD
</span>

QR Codes can be tweaked using the following CSS properties:

• — Sets the error correction level of the QR code. Possible values are L(default), M, Q and H.

• — Sets the size of the quiet (empty) zone around the QR code in modules (QR code "square" widths). The default value is 1. Possible values are 0 (no quiet zone) and positive integers.

• — By default, QR codes are black on white. When setting this property to none, the CSS properties and are used instead.

• — By default, The QR code is built from multiple squares. This method is fast and looks correct in print. However, in PDF viewers on screen the edges of neighboring squares may be visible. When setting this property to high the squares are combined into one object, ensuring a seamless look, at the cost of performance.

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"/>

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="http://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="http://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="http://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() {
            var 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. 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="http://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="http://resources.myserver.com/report.pdf" style="-ro-source-page: 5" />

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":

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

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 is limited to 2 megapixels. This is still large enough to cover an A4 page-sized image with the default supersampling.

JavaScript modes

In addition to disabled and enabled there are additional modes that can improve performance or are required for the correct creation of charts from certain libraries.

JavaScript libraries and frameworks

Proprietary Access to Layout Information

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

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

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

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

var lineDescriptions = boxDescription.lineDescriptions;

var marginRect = boxDescription.marginRect;

var 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 dynamically create PDF attachments, 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: 'myAttachment.txt'
    data: 'This is a text attachment'
});

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

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

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

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

Exporting Data From JavaScript

Sometimes it can be desirable to make data from JavaScript available to the PDFreactor integration for processing after the conversion has finished. You can export data from document JavaScript via the ro.exports JavaScript property. The exported data can then be accessed on the Result object via the getJavaScriptExports() API method.

You can export any data type with ro.exports. However, since the method getJavaScriptExports() 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. If the data can't be converted, a generic string representation of it is used or null if none is available. This means that you can conveniently export JavaScript objects or arrays, and then parse the data back from JSON.

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

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

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 same cases the corresponding CSS.

You can add the library by using the PDFreactor API method setUserScripts(). To add the respective CSS, use the method setUserStyleSheets():

config
    .setUserStyleSheets(new Resource().setUri("awesomizr.css"))
    .setUserScripts(
        new Resource().setUri("awesomizr.js"),
        new Resource().setContent("Awesomizr.createTableOfContents();"));

The capabilities of awesomizr.js include:

• Rotating table headers to reduce the table header width

• Adaptive Page Break Insertion

• Creating a Table of Contents

Bookmarks

PDFreactor adds bookmarks to your document by using the following API method:

config.setAddBookmarks(true);

When the default HTML mode is enabled, the following bookmark levels are applied by default:

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

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

element { -ro-bookmark-level: 1 }

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

Links

PDFreactor can add links to your documents when using the following API method:

config.setAddLinks(true);

When the default HTML mode is enabled, the following link styles are applied by default:

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

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

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

Please also see .

This style is not inherited. It has to be set on the same element as -ro-link.

Comments

It is possible to add PDF comments to the document using the following API method:

config.setAddComments(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: -ro-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: http://docs.oracle.com/javase/7/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: -ro-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: -ro-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: -ro-attr(text);
    -ro-comment-title: -ro-attr(author);
    -ro-comment-style: highlight;

    /* define the comment start element */
    -ro-comment-start: -ro-attr(uid)
}

commentend {
    /* define the comment end element */
    -ro-comment-end: -ro-attr(uid);
}

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:

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

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

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

Interactive PDF Forms

HTML forms are automatically rendered 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 assitive technology like screen readers. Furthermore, it can improve the results of copy and paste and enable advanced export from the PDF, allowing destinations to replicate the document structure and to reflow text.

Using the setAddTags API method, 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 property to enable this feature:

config.setAddTags(true);

To do so you can map XML elements to PDF tag types using proprietary CSS. The relevant properties are and , as well as to some extend and .

"-ro-pdf-tag-type" is used to map an element of the XML language you are using to a PDF tag, for example:

sect1 > title {
    -ro-pdf-tag-type: "H2";
}

The property "-ro-alt-text" is used to specify an alternative description for an XML element. Example:

img {
    -ro-pdf-tag-type: "Figure";
}
img[alt] {
    -ro-alt-text: -ro-attr(alt);
}

You can use the property to define which elements or attributes in the input document are used as the source for the names of form elements in the generated PDF. By default, the names are adopted from the value attribute of the form element.

Using the , the name for radio button groups can be adopted in the same way. By default, it will be adopted from the name attribute of the radio button element.

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 conformant 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 disallowed.

• The PDF must be tagged.

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

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

• Transparency is disallowed. (PDF/A-1 only)

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

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 method setConformance can be used in the PDFreactor integration, e.g.:

config.setConformance(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.setConformance(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 API method setTitle.)

PDFreactor can create PDF/UA compliant documents. Tagging is done by a sophisticated algorithm. For most documents it does not require any manual tweaking to produce results that pass accessibility checks with no errors and little to no warnings.

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

config.setConformance(Conformance.PDFUA);

config.setConformance(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).

• 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 ever 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 .

• If the title is not specified in the input document, it can be set via the API method setTitle.)

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

config.setConformance(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 API method setOutputIntent():

Configuration config = new Configuration();

OutputIntent outputIntent = 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.setOutputIntent(outputIntent);

The method setIdentifier() sets a string identifying the intended output device or production condition in human- or machine-readable form. The method setUrl points to an ICC profile file and the method setData sets the binary data of such a profile, the latter having priority.

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 setPrintDialogPrompt method of the PDFreactor class must be used. Example:

config.setPrintDialogPrompt(true);

PDF Compression

Using the API method setFullCompression, PDF files can be generated with full compression, thus reducing the file size of the resulting PDF document.

Example usage:

config.setFullCompression(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:

config.setEncryption(Encryption.TYPE_128);

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:

config.setUserPassword("upasswd");
config.setOwnerPassword("opasswd");

Both passwords are optional, but recommended for security reasons.

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

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 method setViewerPreferences, e.g.:

config.setViewerPreferences(ViewerPreferences.PAGE_LAYOUT_SINGLE_PAGE,
    ViewerPreferences.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 setMergeDocuments(Resource...) method that declares either URLs to or binary data of existing PDF files.

config.setMergeDocuments(
    new Resource().setUri("http://www.myserver.com/overlaid1.pdf"),
    new Resource().setData(pdfBytes));

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:

config.setMergeDocuments(new Resource().setUri("http://www.myserver.com/appendDoc.pdf"));
config.setMergeMode(MergeMode.APPEND);

Arrange inserts specified pages of PDFs into the generated PDF. This merge mode has to be combined with setPageOrder (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:

config.setMergeDocuments(
    new Resource().setUri("http://www.myserver.com/insertionDoc.pdf"));
config.setMergeMode(MergeMode.ARRANGE);
config.setPageOrder("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:

config.setMergeDocuments(new Resource().setUri(("http://www.myserver.com/overlaid.pdf"));
config.setMergeMode(MergeMode.OVERLAY);

PDFreactor allows to repeat the pages of PDFs with less pages than other PDFs involved in the merger. The API method setOverlayRepeat 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:

config.setOverlayRepeat(Overlay.REPEAT_ALL_PAGES);

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

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.

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

• "pkcs12"

• "jks"

PDFreactor supports the following three modes to sign a PDF:

• Self-signed

• Windows certificate

• VeriSign

To sign a PDF digitally use the API method setSignPDF.

Font Embedding

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

config.setDisableFontEmbedding(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 method should only be used when necessary.

Overprinting

Overprinting means that one color is printed on top of another color. 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. This can be enabled using the API method setAddOverprint:

config.setAddOverprint(true);

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 API method setAddAttachments:

config.setAddAttachments(true);

The following styles can be used to specify attachments:

• :

  A URL pointing to the file to be embedded. This URL can be relative. Specifying "#" will embed the source document.

• :

  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 -ro-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: -ro-attr(href);
    -ro-pdf-attachment-description: content() " (" -ro-attr(href) ")";
}

Attachments can also be set via the API method setAttachments. This method 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"));

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 scrips has to be done differently.

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

PDFreactor allows two ways to add such scripts to the converted PDF. The scripts can be added using the API method addPdfScriptAction. The parameters are the script as a string and the event which should trigger the script.

The known 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.

The second way to set scripts is by using the proprietary CSS property pdf-script-action. By using this property, one can define the PDF scripts in the original document. For more information on this property, please see .

Please note, that the PDF scripts set via the CSS property have a higher priority than those defined via API.

For each trigger event there can be only one script. When setting scripts several times on the same event, only the last one set will be added to the PDF.

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 method setPageOrder, e.g.:

config.setPageOrder("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));

The getDocumentArray() method of the Result object then returns an array of byte arrays, each containing an image representing one page of the document.

Continuous Output

The method setContinuousOutput 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));

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 setOutputFormat

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 full height of the laid out document to be used.

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 style to a named page, the page name is added to the @page rule. The page name is not a pseudo-class as :first is. There is a space between @page and the page name, not a colon.

@page pageName{
    size: letter landscape
}

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.

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.)

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" 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\APDFreactor";
    white-space: pre
}

The result would look like this:

If the first character after the line break is an HTML entity, add an additional space between the "\A" and the entity.

Generated Images

A generated image can be created with the image's URL set as value of the content property.

h1::before{
    content: url("http://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)
}

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 2018 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);
}

Named Strings are similar to in that they can occur multiple times on the same page and are accessed from Page Margin Boxes. Similar to the element() function, the string() function allows to add a second argument to specify which Named String inside a page should be used:

• start

  • Retrieves the latest Named String of the name from previous pages.

  • If there is none, nothing is displayed.

• first

  • Retrieves the first Named String 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 Named String of the name on the page.

  • If there is none, it falls back to the behavior of start.

• last-except

  • If a Named String of the name is on the page, nothing is displayed.

  • If there is none, it falls back to the behavior of start.

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 automatically keep the reference up-to-date with the referenced location, CSS provides the target-counter() and target-text() functions to automatically 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{
    counter-increment: pageCounter;
    @bottom-right{
        content: counter(pageCounter);
    }
}
h1{
    counter-increment: chapterCounter;
}
h1::before{
    content: counter(chapterCounter, upper-roman);
}
a[href]::after{
    content: "Chapter " target-counter(-ro-attr(href url), chapterCounter, upper-roman)
                " on page " target-counter(-ro-attr(href url), pageCounter);
}

a[href]{
    content: target-text(-ro-attr(href url), before) " "
        target-text(-ro-attr(href url), content);
}

Footnotes

A footnote is a text note placed on the bottom of a page. 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 of the page, to show which parts belong together.

For content that is required to have a footnote, the following style can be applied:

float: footnote

.footnote {
    float: footnote;
}
@page {
    @footnote {
        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;
}

2D Transforms

PDFreactor is capable of transforming elements with the property, which makes moving, rotating and scaling document content possible.

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 automatically lays out content inside 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 still 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: always;
}

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;

-ro-bleed-width: 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 trim, bleed and registration marks. The property sets the width of the mark lines, sets their color.

-ro-marks: trim bleed registration;
-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;

The method setPixelsPerInchShrinkToFit

This method 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);

The pixels per inch can also be specified manually.

The property -ro-scale-content

This property must be part of the @page rule and allows the following values:

• A percent value which is treated as a scaling factor for the content.

• The value none causes no scaling.

• The value auto enables the automatic scaling of the content to fit the size of the page.

@page {
    -ro-scale-content: auto;
}

Merge Mode Arrange

The syntax of page order is extended when setting the merge mode to MERGE_MODE_ARRANGE.

With the merge mode selected, PDFreactor requires as usual 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 using a method to specify 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.

config.setMergeMode(MergeMode.ARRANGE);
config.setMergeDocuments(
    new Resource().setUri("http://www.myserver.com/insert1.pdf"),
    new Resource().setUri("http://www.myserver.com/insert2.pdf"));
config.setPageOrder("1, 1:1, 2:A, 2..-1, 1:2");

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.

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");

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, most 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"));

The following table provides an overview of the supported media features. The default values can be found in the PDFreactor API documentation.