PDFreactor is a registered trademark of RealObjects GmbH.
PDFreactor can be deployed in various ways:
Java library: Use this to integrate PDFreactor directly into your Java applications.
Command line: Use the PDFreactor command line application for direct integration into shell scripts.
For details about system requirements and information about the latest changes, please see the
readme
and changelog
files contained within the PDFreactor installation package.
The PDFreactor package comes with two PDFreactor libraries:
pdfreactor.jar — located in the PDFreactor/libs directory
pdfreactor-uber.jar — located in the PDFreactor/libs/uber-jar directory
It is generally recommended to use the pdfreactor.jar. It only contains PDFreactor, while required and optional 3rd party libraries are contained in the required and optional directories, which should be added to the PDFreactor class path manually depending on whether or not they are already installed on the server or their functionality is desired.
For a quick and easy integration of PDFreactor, you can also use the pdfreactor-uber.jar which contains all 3rd party libraries required by PDFreactor. This JAR file is a stand-alone PDFreactor library. No other libraries are required.
Please refer to the README.txt in the PDFreactor/libs directory for more information about the 3rd party libraries.
When using a dependency management system such as Maven, it is recommended to use the pdfreactor.jar in conjunction with the POM file located in PDFreactor/libs/dependencies/pom.xml so that dependencies are included automatically in your application.
To use the PDFreactor on the command line, no installation is required. You just need the pdfreactor-uber.jar file.
PDFreactor Preview is a desktop application that is automatically installed when using one of the PDFreactor installers for Windows or macOS. This application can be used in evaluation or development to quickly convert and preview documents. It is not recommended for use production since it only offers a limited feature set compared to a full PDFreactor integration.
You can integrate PDFreactor by directly using it as a Java library or by running it on the command line.
When integrating PDFreactor into your application, keep in mind your desired workflow. PDFreactor can convert one single HTML or XML document to PDF or image. If you want to convert multiple documents, you have to run multiple conversions. Another important factor is how the input document is supplied. In some workflows, the document already exists on a local or remote server, others might use a template engine to compile and render the document on-the-fly. Depending on the integration and your application, these processes can be parallelized. The following chapters explain comprehensively what steps you have to take to convert a document.
Additional information about the various input and output formats can be found here:
Additional information about the various integration options can be found here:
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.
This part does not apply when using the PDFreactor command line application.
Now that you have a PDFreactor instance (or not if you are using the command line), 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();
Use -
or --
for command line arguments.
The -h
command shows a list of available arguments.
More complex options can be passed with -C config.json
, where config.json is a file
containing a configuration in JSON format.
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.
Use Case | Data Type |
Local document: A document that exists locally on your server's file system. | file URL as string |
Remote document: A document that exists on an external server, accessible via HTTP. | HTTP(S) URL as string |
Dynamically rendered template: A document that is generated from a template and rendered by a template engine. | Content as string or binary* |
* Binary data is represented as a byte array (byte[]
) in Java and .NET, and as a
base64-encoded string in other service clients.
PDFreactor does not support file system paths for the source document directly. To convert a
document on a file system, use a
file URLRFC 8089, i.e.
a URL that starts with file://
followed by the absolute path to the document (on
Windows, this path also
needs to start with a slash).
Use case: A local document exists on the file system at
/local-folder/document.html
(Linux and Mac) or
c:\local-document\document.html
(Windows).
config.setDocument("file:///local-folder/document.html");// Linux/Mac
config.setDocument("file:///c:/local-folder/document.html");// Windows
Linux/Mac:
-i "file:///local-folder/document.html"
Windows
-i "file://c:/local-folder/document.html"
Use case: A remote document that can be accessed via
https://some-server.com/document.html
.
config.setDocument("https://some-server.com/document.html");
-i "https://some-server.com/document.html"
Use case: A template is rendered to a string.
String renderedTemplate = renderMyTemplate(); config.setDocument(renderedTemplate);
-i "<html><body><p>My rendered template</p></body></html>"
The rendered template is represented in the examples above as a variable whose value is computed
by the fictional function renderMyTemplate
,
which represents the business logic in your workflow that would populate and render the template
into a variable of string (or binary) data.
In cases of REST and the CLI, the rendered template must either already exists as a local or
remote document, or the document has to be passed directly
as HTML content. This if of course also possible for all other integration scenarios and
clients, but might not be ideal.
The document
configuration property is required, all other configuration properties are
optional.
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 respective integration-specific chapters:
Conversions in the Java library
Conversions in PDFreactor Command Line Application
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:
Property | Description |
document |
The converted document as binary data. |
documentArray |
The converted multi-image as an array of binary data (each array item represents a separate page image). |
log |
The log of the conversion. See . |
numberOfPages |
The total number of laid out pages. |
numberOfPagesLiteral |
The actual number of pages of the resulting PDF. This page count can differ
from numberOfPages if post-layout steps change the PDF further, such as
.
|
conversionName |
The conversion name as specified in the conversionName
configuration property. |
javaScriptExports |
Data that was exported during JavaScript processing. See . |
exceedingContents |
Exceeding content data if PDFreactor is configured to observe it. See . |
missingResources |
Missing resources if PDFreactor is configured to observe them. See . |
connections |
Connections established during the conversion if PDFreactor is configured to observe them. See . |
The result document can be accessed like this:
byte[] pdfOrImage = result.getDocument(); byte[][] imagePages = result.getDocumentArray();
Use the -o
argument to specify the output document path.
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.
For large documents, it is usually better to stream the result either directly to the file system or to other application components.
Depending on the input documents, PDFreactor may require additional memory. Large and especially complex documents, e.g. documents containing several hundred pages or documents using a complex nested HTML structure, may require even larger amounts of memory. In addition, concurrent conversions also increase memory consumption since they occur simultaneously in the same Java VM.
The exact amount of memory required depends nearly entirely on the input document. Should you run into any issues converting a document, we recommend increasing the memory to e.g. 2GB or higher before attempting another conversion. First signs of memory running short are unusual long conversion times and high CPU usage of multiple threads, even if only one document is being converted.
Should PDFreactor run out of memory, you will usually experience a java.lang.OutOfMemoryError
.
When using the PDFreactor Web Service or a PDFreactor Docker Container, they may crash, since the application
is not recoverable after such an error. Should such a situation occur, it is recommended to increase the
amount of memory available to PDFreactor or to reduce the number of concurrent conversions.
Depending on which PDFreactor integration or application you use, the memory configuration is different.
To adjust the amount of memory available to PDFreactor, you have to start the Java VM with an
appropriate Xmx
parameter, such as -Xmx2048m
for 2GB of memory.
Pass the Xmx
parameter as argument to the java -jar
command.
To increase the amount of memory available to the PDFreactor Preview app, you need to adapt the PDFreactor/bin/PDFreactor Preview.vmoptions file.
To increase the memory to e.g. 4GB, change the parameter to -Xmx2048m
or
-Xmx4g
and restart the PDFreactor
Preview app.
It is not recommended to increase the memory available to PDFreactor to an amount which is greater than the amount of memory available on the system, after subtracting what the OS and other processes already consume. This can lead to instability of the Java VM.
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.
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.
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.
With just a few lines you can create PDFs inside your applications and servlet.
The following sample program converts https://www.realobjects.com/ to PDF and saves it as output.pdf.
import java.io.FileOutputStream; import java.io.IOException; import java.io.OutputStream; import com.realobjects.pdfreactor.PDFreactor; import com.realobjects.pdfreactor.Configuration; import com.realobjects.pdfreactor.Result; import com.realobjects.pdfreactor.Exceptions.PDFreactorException; public class FirstStepsWithPDFreactor { public static void main(String[] args) { PDFreactor pdfReactor = new PDFreactor();// configuration settings
Configuration config = new Configuration();// the input document
config.setDocument("https://www.realobjects.com");// conversion result
Result result = null; try {// render the PDF document
result = pdfReactor.convert(config); byte[] pdf = result.getDocument(); try (OutputStream outputStream = new FileOutputStream("output.pdf")) { outputStream.write(pdf); } catch (IOException e) { e.printStackTrace(); } } catch (PDFreactorException e) {// partial result without PDF
result = e.getResult(); e.printStackTrace(); } } }
The API documentation for details.
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();
When used as a Java library, PDFreactor uses two technologies for logging: The Java logging API (java.util.logging) and SLF4J.
PDFreactor uses the Java Logging API to output information about its progress. To get a
formatted log message, PDFreactor provides
the DefaultHandler
class as a Handler
implementation. A simple console
logger can be created like
this:
Logger pdfReactorLogger = Logger.getAnonymousLogger(); pdfReactorLogger.setLevel(Level.INFO); pdfReactorLogger.addHandler(new DefaultHandler()); config.setLoggers(pdfReactorLogger);
https://docs.oracle.com/javase/8/docs/technotes/guides/logging/
When no Java loggers are specified, PDFreactor logs to SLF4J using
com.realobjects.pdfreactor.PDFreactor
as a logger name.
PDFreactor does not provide a default implementation for SLF4J. If you don't have an implementation already in your classpath, SLF4J will log errors. If logging to neither the Java logging API nor SLF4J is not desired, it is recommended to use the SLF4J NOP bindingshttps://mvnrepository.com/artifact/org.slf4j/slf4j-nop.
PDFreactor provides support for OSGi out of the box. The Manifest of the self-contained variant of PDFreactor (pdfreactor-uber.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 ("pdfreactor.jar" and associated libraries) does not contain appropriate Manifest entries.
If you are using PDFreactor on a system without a graphics environment like X11, you need to enable the headless mode of Java. This can be done by setting the appropriate Java system property. You can either set the property as a Java VM argument or you can set it inside your Java code. it is recommend to set it as early as possible, as changing it affects the entire Java VM instance. In any case it is important to set the property before PDFreactor is instantiated.
java -Djava.awt.headless=true
public class MyPDFreactorIntegration {// set the headless system property
static { System.setProperty("java.awt.headless", "true"); } public void createPDF() { PDFreactor pdfReactor = new PDFreactor()// ...
} }
If the headless mode is not enabled on a system without a graphics environment, you might experience an error similar to this:
java.lang.InternalError: Can't connect to X11 window server using '' as the value of the DISPLAY variable
When running PDFreactor as a command line application or in certain cloud environments, the time required for the cold start of the JRE can be a significant portion of the total time required to convert each document. Note that when running PDFreactor as a library that is part of a larger application, this will only affects the first conversions, so no action is required.
To mitigate this, it is recommended to call the static method PDFreactor.preinit()
before the first conversion, ideally as early as possible. It initializes some PDFreactor classes
in separate threads, significantly reducing the performance penalty of the first conversion.
As a further solution, you could use the Eclipse OpenJ9Eclipse OpenJ9: https://eclipse.dev/openj9/ runtime, specifically its feature "Class Data Sharing"Introduction to class data sharing: https://eclipse.dev/openj9/docs/shrc/. Creating and using a cache for shared classes will significantly improve the cold start time for the command line. This can improve conversion time up to 30% - 50% for smaller documents.
There is an example (a batch file or a shell script, depending on your installation) on how to use the OpenJ9 runtime in path-to-PDFreactor/bin/openj9. Important: It is for reference only and is not intended for productive use. You will have to edit the file and configure the path to your OpenJ9 Java executable in order to use it. You may want to use a different set of OpenJ9 parameters depending on your environment and requirements.
When using the Java library, PDFreactor can write converted documents directly into
OutputStream
s via the
method convert(Configuration, OutputStream)
.
import java.io.FileOutputStream; import java.io.OutputStream; import com.realobjects.pdfreactor.Configuration; import com.realobjects.pdfreactor.PDFreactor; public class ConvertIntoOutputStream { public static void main(String[] args) throws Exception { PDFreactor pdfReactor = new PDFreactor(); Configuration config = new Configuration(); config.setDocument("https://www.realobjects.com"); try (OutputStream outputStream = new FileOutputStream("output.pdf")) { pdfReactor.convert(config, outputStream); } } }
When converting to formats that require one image per page, i.e. most image formats, an
OutputStreamProvider
can be passed to
convert(Configuration, OutputStreamProvider)
to dynamically provide an OutputStream
for each page. The Function
-like
method receives an OutputItem
for information about the page and some advanced control.
This convert
method enables Multi-Image output by
default.
Writing the images to numbered files can be achieved with just one line of code. Output items each
belong to a group. The group in combination with the item number represent
a unique identifier for each file. For programmatic purposes, you can also use the
index
of an output item as a unique identifier. Contrary to the
itemNumber
,
the index
starts at 0 and is unique for each output item of a conversion.
import java.io.FileOutputStream; import com.realobjects.pdfreactor.Configuration; import com.realobjects.pdfreactor.Configuration.OutputFormat; import com.realobjects.pdfreactor.Configuration.OutputType; import com.realobjects.pdfreactor.PDFreactor; public class ConvertIntoDynamicOutputStreams { public static void main(String[] args) throws Exception { PDFreactor pdfReactor = new PDFreactor(); Configuration config = new Configuration(); config.setDocument("https://www.realobjects.com"); config.setOutputFormat(new OutputFormat().setType(OutputType.PNG)); pdfReactor.convert(config, oi -> new FileOutputStream( oi.getGroup().getText() + oi.getPaddedItemNumber() + "." + oi.getFileExtension())); } }
In a similar way conversion results can be written directly into a zip file.
To prevent PDFreactor from automatically closing the ZipOutputStream
OutputItem.setKeepOpen()
can be set to true
:
import java.io.BufferedOutputStream; import java.io.FileOutputStream; import java.util.zip.ZipEntry; import java.util.zip.ZipOutputStream; import com.realobjects.pdfreactor.Configuration; import com.realobjects.pdfreactor.Configuration.OutputFormat; import com.realobjects.pdfreactor.Configuration.OutputType; import com.realobjects.pdfreactor.PDFreactor; public class ConvertIntoZipOutputStream { public static void main(String[] args) throws Exception { ZipOutputStream zos = new ZipOutputStream( new BufferedOutputStream(new FileOutputStream("images.zip"))); Configuration config = new Configuration() .setDocument("https://www.realobjects.com") .setOutputFormat(new OutputFormat().setType(OutputType.PNG)); new PDFreactor().convert(config, oi -> { oi.setKeepOpen(true); zos.putNextEntry(new ZipEntry( oi.getGroup().getText() + oi.getPaddedItemNumber() + "." + oi.getFileExtension())); return zos; }); zos.close(); } }
The OutputStream
s can also be accessed after the item was written, e.g. to retrieve the
data.
The OutputItem
of that callback allows retrieving the OutputStream
previously created for that item:
import java.io.ByteArrayOutputStream;
import java.util.ArrayList;
import java.util.List;
import com.realobjects.pdfreactor.Configuration;
import com.realobjects.pdfreactor.Configuration.OutputFormat;
import com.realobjects.pdfreactor.Configuration.OutputType;
import com.realobjects.pdfreactor.PDFreactor;
public class ConvertIntoCollection {
public static void main(String[] args) throws Exception {
Configuration config = new Configuration()
.setDocument("https://www.realobjects.com")
.setOutputFormat(new OutputFormat().setType(OutputType.PNG));
List<byte[]> imgList = new ArrayList<>();
new PDFreactor().convert(config, oi -> {
oi.setCallback(oic -> imgList.add(
((ByteArrayOutputStream)oic.getOutputStream()).toByteArray()));
return new ByteArrayOutputStream();
});
// use data from 'imgList'
}
}
PDFreactor comes with a command line interface for easy integration in shell scripts or batch files.
It is included in the pdfreactor-uber.jar
which is located in the
PDFreactor/lib/uber-jar directory. For Windows systems a compiled version is provided which
is located in the PDFreactor/bin directory. It can be used like this:
java -jar pdfreactor-uber.jar -i input.html -o output.pdf
Make sure that you are located in the PDFreactor/lib/uber-jar directory when executing the command. Alternatively, you can indicate the full path to the pdfreactor-uber.jar.
For a full list of all arguments and parameters, use the following command:
java -jar pdfreactor-uber.jar --help
When using the Windows executable or the Python Command Line client, replace
java -jar pdfreactor-uber.jar
with
pdfreactor.exe
and
python pdfreactor.py
, respectively.
The Windows executable is located in the PDFreactor/bin directory, the Python client is located in the PDFreactor/clients/cli directory.
The Java command line interface supports standard input and output (stdin
and
stdout
).
To read from stdin
, you have to specify the input argument as "stdin".
To write to stdout
, you have to specify the output argument as "stdout".
Reading from stdin
:
java -jar pdfreactor-uber.jar -i stdin -o output.pdf < input.html
Writing to stdout
:
java -jar pdfreactor-uber.jar -i input.html -o stdout > output.pdf
Combining both:
java -jar pdfreactor-uber.jar -i stdin -o stdout < input.html > output.pdf
PDFreactor can produce a detailed log of the entire conversion. To enable logging you have to set an
appropriate log level first using the
configuration property logLevel
, e.g. like this:
config.setLogLevel(LogLevel.WARN);
--log-level WARN
To retrieve the logs, use the log
property of the Result
object. This gives you
a Log
object and
access to the following logs:
records
property of a Log
object.
recordsCss
property.recordsJs
property.The logs are only populated if logging is enabled. Logs can be retrieved from the Result
object like this:
Log log = result.getLog(); if (log != null) { Record[] mainLog = log.getRecords(); Record[] cssLog = log.getRecordsCss(); Record[] jsLog = log.getRecordsJavaScript(); }
The main log is written to the terminal during the conversion. The CSS and JavaScript logs are not available.
Additionally, you can retrieve the logs using appropriate debug settings. Refer to for more information.
The following examples show how to enable logging by setting an appropriate log level and then appending the log to the generated PDF.
Configuration config = new Configuration(); config.setLogLevel(LogLevel.DEBUG); config.setDebugSettings(new DebugSettings() .setAppendLogs(true));
-d
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.
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);
--log-max-lines 100
If the log capacity is exceeded, the oldest entries will be removed to make room for the new ones.
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.
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.
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);
--license-key "<license>... your license ...</license>"
When converting documents into PDF, it may be desirable to programmatically observe certain parts of the document content to ensure that the PDF result is as excepted. This can be especially important for highly dynamic input documents for which the result might not have been validated prior to the conversion.
There are currently two parts of the content that can be observed: Exceeding content and missing resources. Exceeding content observes content that overflows certain boundaries, missing resources observes all resources that could not be loaded during conversion.
All content observed this way is logged in the normal PDFreactor log. In addition to that, it is logged in separate, machine-parsable logs which can be retrieved and analyzed after the conversion has finished to verify the result.
A content observer can be configured like this:
ContentObserver contentObserver = new ContentObserver();
// set up contentObserver, see below...
config.setContentObserver(contentObserver);
-C config.json
With the following config.json:
{ "contentObserver": {set up contentObserver, see below...
} }
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:
Constant | Description |
ExceedingContentAnalyze.NONE |
Disable this functionality (default) |
ExceedingContentAnalyze.CONTENT |
Analyze content (text and images) only |
ExceedingContentAnalyze.CONTENT_AND_BOXES |
Analyze content as well as boxes. (catches exceeding borders and backgrounds) |
ExceedingContentAnalyze.CONTENT_AND_STATIC_BOXES |
Analyze content as well as boxes, except for those with absolute or relative positioning |
Constant | Description |
ExceedingContentAgainst.NONE |
Disable this functionality (default) |
ExceedingContentAgainst.PAGE_BORDERS |
Find content exceeding the actual edges of the page |
ExceedingContentAgainst.PAGE_CONTENT |
Find content exceeding the page content area. (avoids content extending into the page margins) |
ExceedingContentAgainst.PARENT |
Find content exceeding its parent (i.e. any visible overflow) |
For example:
contentObserver .setExceedingContentAnalyze(ExceedingContentAnalyze.CONTENT_AND_STATIC_BOXES) .setExceedingContentAgainst(ExceedingContentAgainst.PAGE_CONTENT);
--content-observer-exceeding-content-analyze CONTENT_AND_STATIC_BOXES \ --content-observer-exceeding-content-against 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();
Use debug settings to attach the exceeding contents log to the PDF.
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);
--content-observer-missing-resources
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();
Use debug settings to attach the missing resources log to the PDF.
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);
--content-observer-connections
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();
Use debug settings to attach the connections log to the PDF.
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.
It is possible to adjust PDFreactor's default error policy. Depending on the configured policy, the conversion will now fail if certain criteria are met. The following error policies can be set and will terminate the conversion:
LICENSE
The conversion will now fail if no full license key is set. This ensures
that generated PDFs won't contain any
evaluation watermarks.
MISSING_RESOURCE
The conversion will now fail if any resources could not be loaded.
If a detailed list of missing resources is
required, use an appropriate ContentObserver
(see )
instead.
UNCAUGHT_JAVASCRIPT_EXCEPTION
The conversion will now fail if there are uncaught
JavaScript errors in any of the input JavaScript resources, including syntax errors.
CONFORMANCE_VALIDATION_UNAVAILABLE
The conversion will now fail when the PDF's
conformance could not be validated even though conformance
validation was enabled.
The conversion will also fail of the validation module is not available or the conformance
format is not fully supported for validation.
This policy is recommended if you exclusively convert documents where validation is supported and strictly required.
IGNORE_INVALID_MERGE_DOCUMENTS_EXCEPTION
The conversion will no longer fail when
exceptions occur during merge operations (e.g.
when trying to merge encrypted documents for which no owner password or an invalid password was
supplied). PDFreactor now ignores merge documents that cause any exceptions, and they will be
omitted from the final PDF.
WARN_EVENT
The conversion will now fail if any warning event occurs. Warnings
usually don't fail the conversion because a valid result can be produced, but the the
fidelity of the result might be negatively impacted. This error policy ensures that no such
results will be produced.
Error policies can be set like this:
config.setErrorPolicies( ErrorPolicy.LICENSE, ErrorPolicy.MISSING_RESOURCE);
--error-policies LICENSE MISSING_RESOURCE
To limit conversion times and to prevent certain inputs to cause extremely long or even indefinite conversion times, you can specify timeouts. If a timeout is exceeded, the conversion will be aborted.
Conversion times can be limited by specifying a conversionTimeout
in seconds.
config.setConversionTimeout(30);
--conversion-timeout 30
To specifically limit JavaScript processing times, see JavaScript Timeout.
To limit resource loading times, see Resource Timeout. These timeouts will not cause the conversion to abort.
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));
-d
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:
Group | Attachment URL | File | Description |
documents | #, #originalsource |
OriginalSource.txt | The original input document |
#finalsource | FinalSource.txt | The input document after XSLT preprocessing | |
#originaldocument | OriginalDocument.txt | The initially parsed input document | |
#originaldocumentpp | OriginalDocumentPP.txt | A pretty-printed version of the above | |
#finaldocument | FinalDocument.txt | The input document after all modifications (JavaScript etc.) are completed | |
#finaldocumentpp | FinalDocumentPP.txt | A pretty-printed version of the above | |
configuration | #configuration | Configuration.txt | The configuration object passed to the PDFreactor instance |
ClientConfiguration.txt | The configuration object sent to the PDFreactor Web Service (if used) | ||
resources | #resources | Resources.dat | All used external resources like style sheets, scripts, images etc. as a ZIP file |
logs | #log | Log.txt | The main PDFreactor conversion log |
#logcss | LogCss.txt | The PDFreactor CSS log | |
#logjavascript | LogJavaScript.txt | The PDFreactor JavaScript log | |
#systemproperties | SystemProperties.txt | A list of the current Java system properties | |
#connections | Connections.txt | A log of all URL connection attempts performed by PDFreactor | |
#missingresources | MissingResources.txt | A log of all resources that could not be loaded |
Debug settings are intended for investigation purposes only and not for production use. Activating some or all debug settings may change other configuration properties, such as the log level. This is done for convenience to get the most verbose result when debugging.
If only specific debugging tools are required, instead of setting the all
property,
you can
use the appropriate debug settings to enable the desired setting manually. The following
properties are available:
all
— Activates all of the following debugging tools
attachDocuments
— Attaches all debug files belonging to the group
"documents"
attachResources
— Attaches all debug files belonging to the group
"resources"
attachLogs
— Attaches all debug files belonging to the group "logs"
appendLogs
— Appends the PDFreactor log to the generated PDF
forceResult
— Forces PDFreactor to return a result even if an exception
occurred during the conversion
In certain cases where no converted document could be created (e.g. when a specific PDF/A conformance could not be achieved) it may be helpful to have access to the debug files mentioned previously. To do this, it is possible to specify a local directory when configuring the debug settings. If such a directory is specified, PDFreactor will attempt to write all available debug files as a single ZIP into that directory. The local directory can be specified like this:
config.setDebugSettings(new DebugSettings() .setAll(true) .setLocalDirectory(Paths.get("c:\\debug")));
-d c:\debug
PDFreactor will create a ZIP file with the naming scheme
PDFreactor-dump-yyyy-MM-dd-HH-mm-ss-SSS
where yyyy-MM-dd-HH-mm-ss-SSS
represents the serialized date of the dump.
If you only want specific debug files attached, you can forgo enabling the debugging tools entirely and use the feature to make PDFreactor attach the appropriate file. For that, use the URLs mentioned in the Debug Files table.
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));
-I
A license key is required to enable the creation of inspectable documents.
Creating inspectable documents increases the conversion time and may require additional memory.
PDFreactor converts HTML or XML documents which can contain external style sheets, scripts, images or other resources. Depending on the use case, these documents and resources may come from untrusted sources, such as third-party users. This means they might contain malicious code or content which may be used to access private resources through Server-Side Request Forgery.
To protect against potential attacks, PDFreactor has a security layer in place which
restricts certain functionality and filters URLs according to configurable security
settings
via the configuration properties
securitySettings
and customUrlStreamHandlers
.
Depending on your use case and processing chain, you should consider supplementing the security features offered by PDFreactor with your own security measures that can protect your system e.g. on the network layer (such as firewalls), which is beyond the scope of PDFreactor.
When accessing resources from HTTPS, PDFreactor will automatically verify the target SSL certificate. If
the certificate is invalid,
PDFreactor will refuse the connection. If this certificate is still deemed trustworthy (e.g. because
the target is located in the intranet or the certificate is self-signed) or during the development
phase, you can configure PDFreactor to automatically trust all
certificates.
This can be done with the trustAllConnectionCertificates
security property like this:
config.setSecuritySettings(new SecuritySettings() .setTrustAllConnectionCertificates(true));
-k
or --insecure
Please note that this approach is insecure and only recommended if you can verify that the target server is trustworthy.
Whenever PDFreactor attempts a URL connection to a source from an untrusted security context, the URL is vetted against certain criteria before the connection is opened.
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,
although
still works. 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.
When using PDFreactor as a publicly available service or in certain other scenarios, PDFreactor processes configurations that may not have been specified by the integrator or that come from user machines which are by default untrusted environments. Additionally, if at any point in your processing chain it is possible for third parties to inject code or content into the configuration object, then the entire configuration object should be considered untrusted.
To protect yourself, you can use the untrustedApi
property to configure the security
layer
in such a way that PDFreactor treats the API as an untrusted context. This means that all
security checks are also applied
to any resources specified in the PDFreactor configuration object, including the input document.
In addition to that,
machine-specific information is omitted from the logs.
config.setSecuritySettings(new SecuritySettings() .setUntrustedApi(true));
--security-untrusted-api
Input documents may be authored by third parties which don't have the same privileges as
PDFreactor integrators or admins. In this case, it is undesirable that such
authors can override API settings, such as by using . So by
default, PDFreactor prevents access
to these features unless it is specifically allowed via the allowAuthorApiOverrides
security setting.
config.setSecuritySettings(new SecuritySettings() .setAllowAuthorApiOverrides(true));
--security-allow-author-api-overrides
By default, PDFreactor follows redirects automatically. You can disable this with the
allowRedirects
property:
config.setSecuritySettings(new SecuritySettings() .setAllowRedirects(false));
--security-allow-redirects
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.
When PDFreactor vets resource paths according to security policies, it normalizes the path, ignoring any query parameters and the fragment component. Additionally, relative path segments are resolved and non-URI characters are URL encoded. So for the purposes of path vetting, the path
/part/../resource path/file?param=value#fragment
is normalized to
/resource%20path/file
Both the host and the path in connection rules support wildcard patterns, meaning that you can
substitute characters for
the "?" or "*" characters. "?" represents a single wildcard character while "*" represents any
single wildcard
path segment (when used in the path
property) or one domain label (when used in the
host
property).
If you want to represent zero or any number of path segments or domain labels, use "**" instead.
Important: Invalid URI characters (according to RFC 2396) must be URL encoded for path segments!
The matching of hosts is always case-insensitive. The matching of paths is
case-insensitive, unless the
property caseSensitivePath
of the connection rule is set to true
.
Note that path
patterns must always start with a slash.
This example illustrates how to allow connections to the internal host "company-cms" as well as connections to certain paths of a publicly available CDN. All other connections are automatically denied.
config.setSecuritySettings(new SecuritySettings() .setConnectionRules( new ConnectionRule() .setAction(ConnectionRuleAction.ALLOW) .setName("Allow internal company CMS") .setHost("company-cms"), new ConnectionRule() .setAction(ConnectionRuleAction.ALLOW) .setName("Allow public company CDN") .setProtocol("https") .setHost("cdn.company.com"), .setPath("/public%20assets/**")// Encode invalid URI characters
new ConnectionRule() .setAction(ConnectionRuleAction.DENY) .setName("Deny all") .setPath("/**") .setPriority(-1)// Make sure this rule is evaluated last
) );
-C config.json
With the following config.json:
{ "securitySettings": { "connectionRules": [{ "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 }] }}
The pattern
*.pdfreactor.com
matches the hosts
cloud.pdfreactor.com www.pdfreactor.com
but not
pdfreactor.com www.cloud.pdfreactor.com
To match these hosts as well, you could use
**.pdfreactor.com
To allow only CSS files, more specifically files with the extension "css", regardless of the host
and path,
you could use the following path
pattern:
/**/*.css
To ensure that no URLs can be accessed, you can deny all URLs with a rule:
config.setSecuritySettings(new SecuritySettings() .setConnectionRules( new ConnectionRule() .setAction(ConnectionRuleAction.DENY) .setName("Deny all") .setPath("/**") .setPriority(-1) ) );
-C config.json
With the following config.json:
{ "securitySettings": { "connectionRules": [{ "action": "DENY", "name": "Deny all", "path": "/**", "priority": -1 }] }}
Make sure to set the path
property to "/**", so that it works for URL types that do
not have a host
(such as file URLs).
Data URIs and Blobs are not subject to connection security, and thus cannot be blocked by
connection rules since this would be impractical.
The single exception is the allowedProtocols
setting which can be used to block
data URIs or Blobs altogether by
not allowing the "data" or "blob" protocol, respectively.
When using JAR URLs, security rules apply only to the URL to the JAR file, not the whole JAR URL.
When the security settings allow
access to a JAR file, access is also automatically granted to all of its entries. You can
control access to certain JAR entries by using the
entry
property of a connection rule. Entries are treated as paths, so you can use
wildcard notation.
The following rule grants access to all resources inside the "resources" directory in a specific JAR file. Since an entry is specified, the rule does not grant access to the JAR file itself. Also note that the protocol is "file" and not "jar", since rules apply to the URL to the JAR file and not the whole URL.
config.setSecuritySettings(new SecuritySettings() .setConnectionRules( new ConnectionRule() .setAction(ConnectionRuleAction.ALLOW) .setName("Allow access to resources inside a JAR") .setProtocol("file") .setPath("/path/to/my.jar") .setEntry("/resources/**") ) );
-C config.json
With the following config.json:
{ "securitySettings": { "connectionRules": [{ "action": "ALLOW", "name": "Allow access to resources inside a JAR", "protocol": "file", "path": "/path/to/my.jar", "entry": "/resources/**" }] }}
The example above would grant access to e.g. the resource:
jar:file:///path/to/my.jar!/resources/image.png
If an entry is specified for any connection rule, the rule will no longer apply to the URL itself, only the entry. This means that specifying an entry on rules to non-JAR files makes them useless.
Regardless of any more specific rules, access to the JAR itself needs to be ensured first. This means that the "jar" protocol itself needs to be allowed in addition to other adjustments that depend on the used URL.
For example with a Jar URL like
jar:file:///path/to/my.jar!/resources/image.png
, would need the "file" protocol as
well as file system access to load the jar.
In case of a URL like
jar:http://www.jar-server.com/jars/my.jar!/resources/image.png
the "http" protocol would need to be enabled as well as any connection rules needed to access
the URL to the JAR itself.
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.
When using JAR URLs, the URL to the JAR file is also validated against file system access, allowed protocols as well as allowed addresses. Security rules only apply to the URL to the JAR file.
To allow global file system access, you could use the following default settings. This is not recommended when processing content from untrusted sources!
config.setSecuritySettings(new SecuritySettings() .setDefaults(new SecurityDefaults() .setAllowFileSystemAccess(true)));
The CLI allows file system access by default.
To further filter URLs, you can implement custom URLStreamHandlers
java.net.URLStreamHandler
for
specific protocols. These are used before the internal security checks are made. It is also possible
to register such a handler
for all protocols, in this case use an asterisk for the protocol in the API. Only one
CustomUrlStreamHandler
can be used for
a particular protocol. If more are specified, the first one is used. If one for a specific protocol
and one for all protocols is
defined, the one for the specific protocol is always used.
config.setCustomUrlStreamHandlers(
new CustomUrlStreamHandler()
.setProtocol("file")
.setHandler(new URLStreamHandler() {
// your implementation
})
);
config.setCustomUrlStreamHandlers(
new CustomUrlStreamHandler()
.setProtocol("*")
.setHandler(new URLStreamHandler() {
// your implementation
})
);
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.
config.setSecuritySettings(new SecuritySettings() .setAllowNonLocalFileUrls(true));
--security-allow-remote-file-urls
By default, PDFreactor does not load external resources during XML parsing, such as DTDs, entities or
XIncludes.
To allow this for documents, you can use the allowExternalXmlParserResources
property of
the SecuritySettings
.
config.setSecuritySettings(new SecuritySettings() .setAllowExternalXmlParserResources(true));
--security-allow-external-xml-parser-resources
While information about the used PDFreactor version can be generally useful, disclosing version
information can give
potential attackers knowledge of the underlying system who may then develop attacks targeting a specific
version of
PDFreactor. To hide version information, use the security setting
hideVersionInfo
.
config.setSecuritySettings(new SecuritySettings() .setHideVersionInfo(true));
--security-hide-version-info
PDFreactor can process the following input formats. By default, it automatically tries to identify the right
format.
The input format of the source document can be overridden using the documentType
configuration
property.
HTML is rendered by PDFreactor using a default CSS style sheet for HTML in addition to the document's style.
HTML is parsed by the built-in HTML5 parser which parses the document according to HTML5 rules. This
means that elements missing closing tags (such as <p>
without
</p>
) are handled as demanded by the HTML5 specifications.
SVG Elements should be used without having their namespace specified.
You can force HTML processing like this:
config.setDocumentType(Doctype.HTML5);
--document-type HTML5
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);
--document-type 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);
--cleanup-tool TAGSOUP
PDFreactor can also process JavaScript contained or linked in the HTML document. See for further details.
JavaScript processing is only possible when converting HTML, not XML.
Like HTML, XML documents can be styled via CSS. Because XML does not have a default CSS style sheet, you will have to provide one for your specific XML language.
Alternatively or in addition to directly styling the XML content it can be processed by the built-in XSLT Extensible Stylesheet Language Transformations (https://www.w3.org/TR/xslt) processor, either to modify it or to convert it to HTML.
You can force XML processing like this:
config.setDocumentType(Doctype.XML);
--document-type XML
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);
--post-transformation-document-type HTML5 --xslt-mode
PDFreactor automatically detects the encoding of the input document, however the encoding can also be forced to a specific value, e.g. like this:
config.setEncoding("UTF-8");
--encoding "UTF-8"
PDFreactor validates CSS, ignoring unknown properties and property values with invalid syntax. The
cssSettings
configuration
property is used to adjust PDFreactor's default behavior by constructing a CssSettings
object. This object has two properties,
each one responsible for a different aspect of CSS validation:
validationMode
Adjusts the CSS property validation behavior. This effects how PDFreactor validates CSS
property–value
combinations when parsing style sheets. The default value is HTML_THIRD_PARTY
.
supportQueryMode
Adjusts the CSS property support behavior. This effects how PDFreactor interprets the validity of
CSS property–value combinations in CSS "@supports" queries or via JavaScript. The default value
is HTML
.
Both of these properties are configured using one of the constants below:
ALL
Indicates that all style declarations are considered valid disregarding the possibility of improper rendering.
Valid values may be overwritten by invalid style declarations.
HTML
Indicates that all values set in style declarations will be validated as long as PDFreactor supports the corresponding property.
Style declarations for properties not supported by PDFreactor are taken as invalid.
HTML_THIRD_PARTY
Indicates that all values set in style declarations will be validated as long as PDFreactor supports the corresponding property.
Style declarations for properties not supported by PDFreactor but by third party products are taken as valid.
HTML_THIRD_PARTY_LENIENT
Indicates that all values set in style declarations will be taken as valid if a third party product supports the corresponding property.
Style declarations for properties not supported by any third party product but supported by PDFreactor will be validated.
config.setCssSettings(new CssSettings() .setValidationMode(CssPropertySupport.ALL) .setSupportQueryMode(CssPropertySupport.ALL));
--css-validation-mode ALL \ --css-support-query-mode ALL
Legacy HTML versions may have different CSS processing or layout rules. To be compatible, PDFreactor
offers various quirks settings to adjust
its behavior appropriately. This can be done with the quirksSettings
configuration
property. It takes an object with the following
properties:
caseSensitiveClassSelectors
By default in HTML CSS class selectors are case sensitive.
In the default DETECT
mode this behavior is disabled for old HTML doctypes or when
there is no doctype.
minLineHeightFromContainer
By default the line-height of text containers, e.g. paragraph elements, is used as the minimum line-height of their lines.
In the default DETECT
mode this behavior is disabled for old HTML doctypes or when
there is no doctype.
Each of these properties is configured with a QuirksMode
constant to enable or disable it
independently of the document:
STANDARDS
Forced no-quirks (i.e. standard compliant) behavior.
QUIRKS
Forced quirks behavior.
DETECT
Doctype dependent behavior.
config.setQuirksSettings(new QuirksSettings() .setCaseSensitiveClassSelectors(QuirksMode.QUIRKS);
quirks--case-sensitive-class-selectors QUIRKS
PDFreactor automatically loads linked external resources, e.g. from tags like <link>
,
<img>
etc. If the respective server does not respond within 60 seconds, loading of
the resource will be aborted and it will not be
included in the document.
For documents including relative resources, like
<img src="images/a.png" />
<a href="/english/index.html">...</a>
<link href="../css/layout.css" rel="stylesheet" type="text/css" />
PDFreactor needs a base URL Uniform Resource Locator (https://www.w3.org/Addressing/) to resolve these resources. If your input document source is a URL, the base URL will be set automatically. In all other cases you have to specify it manually:
config.setBaseUrl("https://someServer/public/");
--base-url "https://someServer/public/"
It is also possible to specify file URLs:
config.setBaseUrl("file:///directory/");
--base-url "file:///directory/"
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.
Resource loading timeouts can be customized. Timeouts in milliseconds can be configured
via the connectTimeout
and readTimeout
network settings.
The connect timeout is the timeout in establishing the initial connection to the resource server, the read timeout is the timeout in downloading the resource from the server (after establishing the connection).
These timeouts can be configured like this:
config.setNetworkSettings(new NetworkSettings() .setConnectTimeout(1000) .setReadTimeout(1000));
--network-connect-timeout 1000 \ --network-read-timeout 1000
PDFreactor supports resource loading from HTTPS and will automatically verify the target SSL certificate. Sometimes this can lead to PDFreactor refusing the connection due to issues with the certificate. For more information please refer to .
When resources are behind authentication, PDFreactor can automatically send appropriate HTTP
headers to gain access.
You can specify the username and the password for the credentials via the
authenticationCredentials
property. This property is a collection of HttpCredentials
objects that are used to
specify various
properties of the authentication and the target server. PDFreactor will automatically select the
credentials
whose properties best match the target server's authentication request.
The following properties can be specified:
username
– The username. This property is required.
password
– The password. This property is required.
authScheme
– The authentication scheme, chosen from a list of constants. If
set, PDFreactor only uses these credentials when connection to a server whose
authentication scheme matches the specified scheme.
host
– The host. If set, PDFreactor only uses these credentials when
connecting to the specified host.
port
– The port. If set, PDFreactor only uses these credentials when
connecting to a server using the specified port.
protocol
– The HTTP protocol. If set, PDFreactor only uses these credentials
when connecting to a server over the specified protocol.
realm
– The authentication realm. If set, PDFreactor only uses these
credentials when connecting to a server whose authentication challenge matches the
specified realm.
config.setNetworkSettings(new NetworkSettings() .setAuthenticationCredentials(new HttpCredentials() .setUsername("username") .setPassword("password") .setAuthScheme(HttpAuthScheme.DIGEST) .setRealm("My Realm")));
-C config.json
With the following config.json:
{ "networkSettings: { "authenticationCredentials": [ "username": "username", "password": "password", "authScheme": "DIGEST", "realm": "My Realm" ] }}
Sometimes external resources require additional HTTP headers. PDFreactor will always send all
configured headers when requesting
resources. HTTP headers can be specified via the requestHeaders
configuration
property
of the networkSettings
object.
Resource servers may have a white list of user agents to which they deliver content. While PDFreactor always sends a default user agent header, it can be overridden if necessary.
config.setNetworkSettings(new NetworkSettings() .setRequestHeaders( new KeyValuePair("User-Agent", "MyApp/2.0"));
-C config.json
With the following config.json:
{ "networkSettings": { "requestHeaders": [ { "key": "User-Agent", "value": "MyApp/2.0" } ] }}
Some external resources require cookies, especially when trying to access
session-specific resources. PDFreactor features RFC 6265-compliant cookie handling and will send
and store appropriate cookies with each request and response.
The cookie store persists for the duration of the entire conversion. If you want a persistant
cookie store that exists beyond the lifetime of conversions, use a
User Agent.
Cookies as well as PDFreactor's cookie policy can be specified via the cookies
and
cookiePolicy
configuration parameters of the networkSettings
object, respectively.
Cookies have the following properties:
name
– The name of the cookie. This property is required.
value
– The value of the cookie. This property is required.
domain
– The domain attribute of the cookie. Specifies to which hosts the
cookie is sent by PDFreactor. Applies to any domain if not specified.
Note that this behavior is an intentional deviation from the RFC standard which does not
allow cross-domain cookies. This is to ensure ease of use and backwards compatibility.
path
– The path attribute of the cookie. Specifies the path which must exist
in the target URI for PDFreactor to send the cookie. Applies to any path if not
specified.
secure
– The secure attribute of the cookie. Specifies whether this cookie
will only be sent over secure connections like HTTPS.
A common use case for a custom cookie are session cookies that need to be sent for each resource request so that PDFreactor has access to a user's session. This is relevant when PDFreactor is integrated into a session-based web application. Usually, you would have to find a way to read the session cookies. The example uses a static example value instead.
config.setNetworkSettings(new NetworkSettings() .setCookies(new Cookie() .setName("JSESSIONID") .setValue("123456789")));
-C config.json
With the following config.json:
{ "networkSettings: { "cookies": [ "name": "JSESSIONID", "value": "123456789" ] }}
The cookie policy defines how PDFreactor handles cookies set by the server.
DISABLED
– Disables cookie handling entirely. Cookies specified via the
cookies
configuration property are still sent, but server cookies are
automatically rejected and not processed.
STRICT
– A strict standard-compliant cookie policy.
RELAXED
– Same as STRICT
, but PDFreactor ignores any date
issues in the cookies. This is the default behavior.
A cookie policy can be set like this:
config.setNetworkSettings(new NetworkSettings() .setCookiePolicy(CookiePolicy.RELAXED));
--network-cookie-policy RELAXED
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.
The following sample rewrites all URLs beginning with "http://myOldHost/" to URLs that begin with "https://myNewHost/".
config.setUrlRewriteSettings(new UrlRewriteSettings() .setRules( new UrlRewriteRule() .setPattern("^http://myOldHost/(.*)$") .setSubstitution("https://myNewHost/$1") ) );
-C config.json
With the following config.json:
{ "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.
Data URLs are also matched, but before the match the data part is removed. This means you can still match the header, but not the actual data.
Since only the result URLs of the rewrite are used to open connections, security settings only apply to the new URLs and not the original ones.
In certain cases it is desirable to load additional resources, such as style sheets or scripts, without modifying the contents of the input document. This can be achieved by specifying the resources directly in the PDFreactor integration code instead of the document itself.
All of these resources use the Resource
model. They are usually specified by a URL or by
content.
If both content
and uri
properties are set, the uri
is used as a
base URL
for the resource.
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"));
-c "p { color: red; }" http://myServer/my.css
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"));
--integration-style-sheets "p { font-family: sans-serif }" http://myServer/corporate-identity.css
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"));
-j "console.log('executed first')" http://myServer/my.js
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"));
--xslt-style-sheets http://myServer/my.xsl
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.
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 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.
The functions rgb and rgba share the same syntax and can be used interchangeably, so
rgb(0%,100%,0%,50%)
will also result in a semi-translucent blue.
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);
--color-space-target-color-space CMYK
CMYK colors are also supported in SVGs.
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 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.
Different colors can be converted into a common color space. See for more information.
In addition to rendering HTML and XML styled with CSS, PDFreactor is also able to render documents with
compound formats such as images, SVGs or barcodes, so-called replaced element
s.
The replaced elements can be mapped to arbitrary elements using styles.
You can use namespaces to include other document formats to integrate XML elements from a different namespace directly within your document.
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.
Corrupted images, embedded "as-is", may lead to corrupted PDF output.
PDFreactor needs to access image data multiple times during the conversion. It needs to know an
image's dimensions during layout, and then the actual binary data to embed it in the PDF during
rendering.
To avoid having to download the image multiple times and thus slowing down the conversion,
PDFreactor keeps downloaded images in memory for quick access. However, in certain scenarios,
images can be quite
large, e.g. high-resolution TIFFs for print. In this case, it can actually be detrimental to
keep the image in memory. You can use the processingPreferences
configuration
object to
change the default behavior of PDFreactor. The value SAVE_MEMORY_IMAGES
prevents
PDFreactor from keeping images in memory. Instead, they are downloaded each time PDFreactor
requires data.
config.setProcessingPreferences( ProcessingPreferences.SAVE_MEMORY_IMAGES);
--processing-preferences SAVE_MEMORY_IMAGES
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.......
When using non-HTML5 documents, an SVG namespace has to be added and used:
<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>
SVGs are embedded into the PDF as vector graphics, keeping them resolution independent. However, SVGs containing masks, filters or non-default composites Default composites use the src-over operator with an opacity of 1. Other compositing operations, especially those with an opacity that is not 0, are considered non-default and will cause the SVG to be rasterized. have to be rasterized Rasterization is the task of taking an image described in a vector graphics format and converting it into a raster (pixel) image.. This behavior can be configured using CSS:
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.
PDFreactor supports CMYK and spot colors in SVGs. Those are passed to the PDF as-is, as long as the SVG is not rasterized.
stroke="cmyk(0.0, 0.0, 0.0, 1.0)"
When SVGs are converted to PDF vector graphics text can either be embedded as text, using a font, or as shapes.
The former allows selecting and copying the text and results in smaller output file size when there is a
significant amount of SVG text. It is also the default behavior, which can be overridden via the custom CSS property
, specified on the root of the SVG. Specifying a stroke
color forces rendering as shapes. In certain complex scenarios embedding as text may also be disabled.
The supported styles include the common font styles and letter-spacing
.
Supported attributes include text-anchor
, textLength
and lengthAdjust
.
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.
While the combined configuration MML_SVG
typically works, it is
recommended to use the following configuration which is optimized for use in PDFreactor:
<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>
The configuration above is automatically applied when using Awesomizr to load MathJax:
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.
PDFreactor supports MathJax with the following limitations:
Support for version 2 only. We recommend using the most recent release of that version to display MathML. MathJax v3 is currently not suported.
SVG output only. Other output processors currently don't produce optimal results.
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).
The behavior of most of the -ro-barcode-*
properties depends on the selected barcode
type.
A full list of all supported barcode types, their subtypes and applicable CSS properties can be found in the appendix.
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
.
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.
By default, all barcodes will be rendered in black with a transparent background.
To change the foreground color, you can use the
-ro-barcode-color
property. If it is
set to
currentColor
, the value of the color
property will
be used.
When adjusting the size of the barcode, you should differentiate between two aspects: On the one hand, there is its natural size (also called intrinsic size), which is the size the barcode itself would have without the influence of the layout around it. It depends on factors like the barcode type, its content and certain settings, for example its ecc level.
And on the other hand, there is the specific size (also called extrinsic size), which is the size the barcode actually consumes in the layout and the resulting document. It depends on the context and CSS styles of the barcode element.
The replaced element will be adjusted automatically to comply with the surrounding
document's layout.
However, as the aspect ratio is not always preserved, this might result in distorted
barcodes, i.e. having
an incorrect aspect ratio.
This can be prevented by setting the
object-fit
property
to contain
.
For some barcode types, the
-ro-barcode-size
property can be used to select a certain sized version.
E.g. for a QR code, setting
-ro-barcode-size
to 10
would result in a version 10 QR code, which contains 57 x 57 modules.
For other types, like
databar-expanded
, the
property adjusts the amount of columns which should be used to store data.
Applied to PDF417 codes, the property can additionally be used to adjust how many rows are
rendered.
The value defined by
-ro-barcode-size
might be
ignored in some cases, like when the selected size is not sufficient to store the specified
amount of
data.
If applied to a one dimensional barcode, the property sets the bar height.
More detailed descriptions on how
-ro-barcode-size
behaves depending
on the used
barcode type can be found in the appendix.
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"; }
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"/>
Besides flash you can also embed various other formats, e.g. videos. The data is embedded in the PDF, but whether or not it is displayed depends on the formats supported by your PDF viewer.
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
.
Using CSS, the behavior can be made more browser-like if desired. The following example simulates the appearance of checkboxes and radio buttons in web browsers and prevents other styles from interfering with them. It contains CSS properties that are commonly used on form elements and uses values to approximate browser rendering.
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; }
Note that the list of styles is not exhaustive and that the styles used are not necessarily ideal for interactive controls.
An iframe allows another document, for example content from other pages, to be embedded inside an existing one.
There are two ways to define the inner document of an iframe. The first option is to use the
src
attribute and specifying the
URL from which the document should be loaded. The URL might be absolute or relative and should
refer to an HTML document.
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>
If both attributes have been set, srcdoc
has priority over src
.
If the seamless
attribute has been set, the iframe's document behaves as it would
be in the document that contains the iframe.
That means that the width and height of the iframe are ignored and the inner document is shown
completely if possible.
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>
Generally, true
and false
are INVALID values for boolean attributes.
Using CSS styles, it is possible to customize the look and functionality of iframes.
The border, padding and margin can be set or removed with the appropriate styles.
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>
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>
PDFreactor by default does not use a resolution-dependent bitmap as the core of the canvas. Instead it converts the graphics commands from JavaScript to resolution-independent PDF objects. This avoids resolution-related issues like blurriness or pixelation.
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.
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; }
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).
When creating soft shadows or using blur filters, the blurring itself is a time-consuming task and can, depending on the content to be generate, increase the creation time of the PDF significantly. Thus blurs and shadows should be used with caution if the conversion time of the PDF is important.
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.
If the only filter function used is opacity
, consider using the CSS property opacity instead. PDFreactor uses native PDF functionality
to render the transparent element, thus avoiding the
drawbacks of rasterization.
This chapter refers to JavaScript in the input document, processed by PDFreactor like in a browser. There is also:
PDFreactor automatically processes JavaScript that is embedded into or linked from input HTML documents.
It is also possible to manually add scripts:
config.setUserScripts( new Resource().setContent("console.log('test')"));
-j "console.log('test')"
If desired, this functionality can be disabled as follows:
config.setJavaScriptSettings(new JavaScriptSettings() .setDisabled(true));
-javascript-disabled
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.
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));
--javascript-javascript-engine RHINO
PDFreactor supports various third-party JavaScript libraries and frameworks. See for details.
PDFreactor allows JavaScript access to some layout information via the proprietary object ro.layout.
Many proprietary JavaScript functions return so-called Description
objects:
PageDescription
, BoxDescription
, etc. These objects provide layout
information on the specific type of document item, such as a document page.
The description objects contain information about the layout of its content. The properties of , and can be found in the appendix JavaScript Objects And Types
Description objects are snapshots of the particular moment they were created. Changing the document after getting one has no effect on them.
Describes the dimensions of a page and its rectangles as well as some further information.
The rectangles are described by using DOMRect
. A is retrieved via the index of the desired page. The first page has the
index 0.
let pageDesc = ro.layout.getPageDescription(1);
Describes the position and dimensions of the rectangles of a box as well as some further
information. The rectangles are described by using DOMRect
. A is retrieved via a DOM element, which may have
a box, multiple ones or none.
let element = document.querySelector("#myElem"); let boxDescriptions = ro.layout.getBoxDescriptions(element); if (boxDescriptions.length > 0) { let boxDescription = boxDescriptions[0]; }
Contains information about a line of text. It can be retrieved from a .
let lineDescriptions = boxDescription.lineDescriptions;
A DOMRect
contains the position and dimensions of a rectangle.
(see MDN)
To retrieve the DOMRect
from Page- and BoxDescription use the getter functions that
take an optional string parameter. This
parameter specifies the length unit of the values of the DOMRect
and has to be one
of the following absolute CSS units: "px",
"pt", "pc", "cm", "mm", "in" or "q". By default this value is "px".
let marginRect = boxDescription.getMarginRect("cm");
A Range
represents a fragment of a document that can contain nodes and parts of text nodes.
(see MDN)
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.
This feature is disabled by default and needs to be explicitely enabled by allowing author API overrides.
Trying to access the ro.pdf
object when it is disabled causes an error to be
thrown, which can be caught and handled in the surrounding JavaScript.
In some cases it might be desirable to specify PDF attachments not in the PDFreactor API, but dynamically via JavaScript, depending on the document. This example shows how to add a PDF attachment from JavaScript.
ro.pdf.attachments.push({ name: "log.txt", data: "My log text.", description: "A JavaScript log" });
The data to attach can also be binary, e.g. an image generated by a canvas
.
graphCanvas.toBlob((graphBlob) => { ro.pdf.attachments.push({ name: "graph1975.png", data: graphBlob, description: "Statistics of 1975" }); });
This example uses a custom page order to eliminate the third page from the document.
ro.pdf.pageOrder = "1..2,4..-1";
Even if the integration code specifies an author and a title in the configuration, these values can be overridden at runtime.
Original configuration:
config.setAuthor("Brian Greene"); config.setTitle("The Elegant Universe");
--author "Brian Greene" --title: "The Elegant Universe"
Override at runtime:
ro.pdf.author = "Stephen Hawking"; ro.pdf.title = "The Universe in a Nutshell";
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.
While it is possible to export strings directly, it is generally recommended to only export
JavaScript arrays or objects which will be converted
into JSON. If an empty string is exported, it is converted to null
when accessed through the Result
object in the
PDFreactor integration.
Export an object:
ro.exports = { message: "my exported data", content: [ 1, 2, 3 ] };
The resulting string is as follows:
{"message":"my exported data","content":[1,2,3]}
It can be retrieved from the javaScriptExports
property of the Result
object:
String javaScriptExports = result.getJavaScriptExports();
Not possible.
This string can then be parsed or processed further.
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.
Name | Description | Default Value |
maxScriptElements |
The maximum number of script elements in the document (including ones
generated by JavaScript)
to be processed.That amount of elements does not have to be in the document
simultaneously.
|
1,000,000 |
maxQueuedTasks |
The maximum number of tasks to be processed. Tasks include everything that introduces
JavaScript
to be run, e.g. the callbacks of events, observers and window.setTimeout .
|
1,000,000 |
maxTasksWithoutDomChange | The maximum number of tasks to be processed while the DOM is not modified. | 1,000 |
maxTasksRepeated | The maximum number of times the same tasks can be processed. These executions of the task do not have to be consecutive. | 1,000 |
maxVirtualTimeOffset |
The maximum number of seconds the virtual time of the JavaScript environment may be
forwarded.
Virtual time is forwarded when callbacks of window.setTimeout and similar
function are executed.
It is not related to the wall-clock time in any way.
|
3,600 (1h) |
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.
Name | Description | Default Value |
statementLimit | The maximum number of JavaScript statements to be executed. Statements include, among other things, method calls, variable assignments and loop iterations. | 1,000,000,000 (1 billion) |
timeout | The maximum number of seconds (wall-clock time) JavaScript processing may take. This is not related to the virtual time in any way. | 3,600 (1h) |
The following example limits JavaScript processing time to 20 seconds.
config.setJavaScriptSettings(new JavaScriptSettings() .setTimeout(20));
--java-script-timeout
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));
-c awesomizr.css -j module "import * as Awesomizr from './awesomizr.js'; Awesomizr.createTableOfContents();"
Of course, the library and the style sheet can alternatively be imported by the document itself. However, please note that some functions only work with PDFreactor.
The capabilities of awesomizr.js include:
PDF is the default output format of PDFreactor.
Generally PDFreactor generates PDFs with the Adobe PDF version 1.5. However, some PDF features may require viewers that support newer versions of PDF.
PDF/A and PDF/X conformance may force different PDF versions.
The PDF documents created with PDFreactor may contain additional metadata, which may require a PDF reader that is able to display a later version of Adobe PDF correctly.
Some features of PDFreactor are specific to the PDF output format:
PDFreactor adds bookmarks to your document automatically. This can be disabled by using the
disableBookmarks
configuration property like this:
config.setDisableBookmarks(true);
--disable-bookmarks
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; }Using this property, one can structure the specified elements within the bookmark view of the PDF viewer. The elements are ordered in ascending order. The element with the lowest bookmark level is on top of the bookmark hierarchy (similar to HTML headlines). Several bookmark levels can be set using the
bookmark-level
style.
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.
PDFreactor adds links to your documents by default. This can be disabled by using the
disableLinks
configuration property like this:
config.setDisableLinks(true);
--disable-links
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); }
Some PDF viewers recognize URLs written in plain text and convert them to links. This happens independently of PDFreactor and its settings and properties.
Please see for a way to embed target files into the output PDF instead of linking to them.
The proprietary property can be used to specify how the 'clickable' areas of links are determined.
This style is not inherited. It has to be set on the same elements as -ro-link, when those should
deviate from the default value: all
.
How the coordinate to scroll to is determined for internal links can be changed via the property on the target element, 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.
When links are enabled the following also create clickable links:
Links in SVGs. The target is taken from the a
element itself. The clickable
area is the bounding rectangle of all elements contained in that element.
HTML image map links. The clickable area and target are based on the attributes of the
area
.
Barcodes containing an absolute URL. Those are clickable in their entirety pointing to that URL.
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 .
When a metadata property applies to multiple elements the values are concatenated. Therefore it is recommended to disable the default set elements when specifying other ones:
/* 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");
--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:
The PDF "producer" property, also known as "encoding software", cannot be overridden. It will always contain PDFreactor's name and version as well as basic information about the used license. For security purposes, the version number can be suppressed. See for more details.
You can also add custom properties to the documents, for which you can define the name and value, e.g.
config.setCustomDocumentProperties( new KeyValuePair("feedback address", "peter@miller.com"));
--customDocumentProperties "feedback address" "peter@miller.com"
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; }Using this style declaration, only the form with the ID "credentials" and the input fields contained in this form are converted to an AcroForm when the PDF is rendered. Only the forms and form elements having this CSS style are converted. You can convert all forms and input fields using this CSS code:
form, form input { -ro-pdf-format: pdf; }
Markup | Mapped Form Type |
<input type="text"/>
|
Text Box |
<input type="password"/>
|
Text Box |
<input type="checkbox"/>
|
Check Box |
<input type="radio"/>
|
Radio Button |
<input type="submit"/>
|
Push Button |
<input type="reset"/>
|
Push Button |
<input type="file"/>
|
Text Box |
<input type="hidden"/>
|
None |
<input type="image"/>
|
Push Button |
<input type="button" value="Button"/>
|
Push Button |
<input type="color"/>
|
Text Box |
<input type="date"/>
|
Text Box |
<input type="datetime-local"/>
|
Text Box |
<input type="date"/>
|
Text Box |
<input type="email"/>
|
Text Box |
<input type="month"/>
|
Text Box |
<input type="number"/>
|
Text Box |
<input type="range"/>
|
Text Box |
<input type="search"/>
|
Text Box |
<input type="tel"/>
|
Text Box |
<input type="time"/>
|
Text Box |
<input type="url"/>
|
Text Box |
<input type="week"/>
|
Text Box |
<button type="submit">Submit</button>
|
Push Button |
<button type="button">Button</button>
|
Push Button |
<button type="reset">Reset</button>
|
Push Button |
<select>
|
Combo Box |
<select multiple>
|
List Box |
<textarea></textarea>
|
Text Area |
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);
--add-tags
PDF tagging is automatically enabled when it is required by a PDF conformance, like PDF/A-1a, PDF/A-3a or PDF/UA.
For documents containing text in RTL direction that have to be
accessible the property
must not be set to speed
, as that does only ensure that the text is in the
correct order visually, but not logically.
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);
--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.
Images in PDF/A-1 document may have an alpha channel. However, the values in the channel may only be the minimum and maximum, i.e. fully transparent and fully opaque. For images that violate that requirement PDFreactor applies dithering to the alpha channel to create a valid one that approximates the original.
CSS colors may also not have alpha values. Those are not automatically removed.
This can be enabled with the ignoreAlpha
configuration property, like this:
config.setIgnoreAlpha(true);
--ignore-alpha
Please note that ignoring the alpha channel may lead to unexpected results.
PDFreactor can optionally validate the generated PDF against specified PDF/A or PDF/UA
conformances using the configuration
property validateConformance
. Validation is optional and might take several minutes
depending on the size
and complexity of the document. It can be enabled like this:
config.setValidateConformance(true);
--validate-conformance
When conformance validation is enabled, PDFreactor will throw an exception and terminate the conversion should the document not validate against all specified conformances. If the PDF validates successfully, the conversion will finish normally. In either case, the log will contain additional information about the document’s validation status.
It is also possible to create documents that are
PDF/UA
compliant in addition to being PDF/A compliant, combining the benefits of both formats for
maximum
accessibility and archivability. We highly recommend adding PDF/UA conformance when creating
PDF/A documents:
config.setConformance(Conformance.PDFA3A_PDFUA);
--conformance "PDFA3A_PDFUA"
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);
--conformance "PDFUA"
It is also possible to create documents that are PDF/A compliant in addition to being PDF/UA compliant, combining the benefits of both formats for maximum accessibility and archivability. We recommend adding PDF/A-3a conformance when creating PDF/UA documents, as long as the additional restrictions are met by the input document.
config.setConformance(Conformance.PDFA3A_PDFUA);
--conformance "PDFA3A_PDFUA"
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);
--conformance "PDFX4"
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) );
--output-intent-identifier "ICC profile identifier" \ --output-intent-url URL/to/ICC/profile
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.
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));
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%) }"));
--color-space-cmyk-icc-profile URL/to/ICC/profile \ --color-space-target-color-space RGB \ --color-space-conversion-enabled
If cmykIccProfile
is not set, naive conversion, similar to the one of PDF viewers, is
used.
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);
--print-dialog-prompt
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.
In some cases, the PDF contains many high-resolution images which are appropriate for print PDFs, but may not be ideal for PDFs published on the web. For such a case, you can use CSS to compress and resample images to ensure that their resolution does not exceed a specific value. This can be done with the proprietary CSS property , whose value represents the target resolution.
This example demonstrates how to convert large images into new images with a target resoluton of 72dpi. Images that already have resolution smaller than 72dpi are not converted.
* { -ro-image-resampling: 72dpi; }
Changing the resolution of an image is generally a lossy compression and will reduce the quality of an image. To specify the compression algorithm and the quality of the resampled image, use the proprietary CSS property.
PDFreactor automatically compresses certain PDF data strucutres such as tag trees to optimize the
file size. There may be certain situations where this optimization is undesired, e.g.
when PDF version 1.4 is required. In this case, the optimization can be disabled using the
disablePdfStructureOptimization
configuration property.
config.setDisablePdfStructureOptimization(true);
--disable-pdf-structure-optimization
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);
encryption-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);
--encryption-user-password "upasswd" \ --encryption-owner-password "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:
Encryption as well as restrictions are highly viewer dependent. If a PDF viewer does not implement them, some restrictions may not be taken into account at all.
Property name | Allows ... |
allowPrinting |
printing |
allowCopy |
copying or otherwise extracting content |
allowAnnotations |
adding or modifying annotations and interactive form fields |
allowModifyContents |
modifying the content of the document |
allowDegradedPrinting |
printing (same as allowPrinting , however, with a limited resolution) (128
bit encryption only)
|
allowFillIn |
filling in form fields (128 bit encryption only) |
allowAssembly |
inserting, removing and rotating pages and adding bookmarks (128 bit encryption only) |
allowScreenReaders |
extracting content for use by accessibility devices (128 bit encryption only) |
API docs for further information.
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);
--viewer-preferences PAGE_LAYOUT_SINGLE_PAGE DISPLAY_DOC_TITLE
PDFreactor supports the following viewer preferences:
Viewer Preference | Effect |
PAGE_LAYOUT_SINGLE_PAGE |
Display one page at a time. |
PAGE_LAYOUT_ONE_COLUMN |
Display the pages in one column. |
PAGE_LAYOUT_TWO_COLUMN_LEFT |
Display the pages in two columns, with odd numbered pages on the left. |
PAGE_LAYOUT_TWO_COLUMN_RIGHT |
Display the pages in two columns, with odd numbered pages on the right. |
PAGE_LAYOUT_TWO_PAGE_LEFT |
Display two pages at a time, with odd numbered pages on the left. |
PAGE_LAYOUT_TWO_PAGE_RIGHT |
Display two pages at a time, with odd numbered pages on the right. |
PAGE_MODE_USE_NONE |
Show no panel on startup. |
PAGE_MODE_USE_OUTLINES |
Show bookmarks panel on startup. |
PAGE_MODE_USE_THUMBS |
Show thumbnail images panel on startup. |
PAGE_MODE_FULLSCREEN |
Switch to full screen mode on startup. |
PAGE_MODE_USE_OC |
Show optional content group panel on startup. |
PAGE_MODE_USE_ATTACHMENTS |
Show attachments panel on startup. |
HIDE_TOOLBAR |
Hide the viewer application's tool bars when the document is active. |
HIDE_MENUBAR |
Hide the viewer application's menu bar when the document is active. |
HIDE_WINDOW_UI |
Hide user interface elements in the document's window. |
FIT_WINDOW |
Resize the document's window to fit the size of the first displayed page |
CENTER_WINDOW |
Position the document's window in the center of the screen. |
DISPLAY_DOC_TITLE |
Display the document's title in the top bar. |
NON_FULLSCREEN_PAGE_MODE_USE_NONE |
Show no panel on exiting full-screen mode. Has to be combined with PageModeFullScreen. |
NON_FULLSCREEN_PAGE_MODE_USE_OUTLINES |
Show bookmarks panel on exiting full-screen mode. Has to be combined with PageModeFullScreen. |
NON_FULLSCREEN_PAGE_MODE_USE_THUMBS |
Show thumbnail images panel on exiting full-screen mode. Has to be combined with PageModeFullScreen. |
NON_FULLSCREEN_PAGE_MODE_USE_OC |
Show optional content group panel on exiting full-screen mode. Has to be combined with PageModeFullScreen. |
DIRECTION_L2R |
Position pages in ascending order from left to right. |
DIRECTION_R2L |
Position pages in ascending order from right to left. |
PRINTSCALING_NONE |
Print dialog default setting: disabled scaling |
PRINTSCALING_APPDEFAULT |
Print dialog default setting: set scaling to application default value |
DUPLEX_SIMPLEX |
Print dialog default setting: simplex |
DUPLEX_FLIP_SHORT_EDGE |
Print dialog default setting: duplex (short edge) |
DUPLEX_FLIP_SHORT_EDGE |
Print dialog default setting: duplex (long edge) |
PICKTRAYBYPDFSIZE_FALSE |
Print dialog default setting: do not pick tray by PDF size |
PICKTRAYBYPDFSIZE_TRUE |
Print dialog default setting: pick tray by PDF size |
The PAGE_LAYOUT_
preferences are overridden by the @-ro-preferences
properties
and .
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);
--merge-documents https://www.myserver.com/overlaid1.pdf
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);
--merge-documents https://www.myserver.com/appendDoc.pdf \ --merge-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");
--merge-documents https://www.myserver.com/insert1.pdf https://www.myserver.com/insert2.pdf \ --merge-mode ARRANGE \ --page-order "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);
--merge-documents https://www.myserver.com/overlaid.pdf \ --merge-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);
--merge-documents https://www.myserver.com/overlaid.pdf \ --merge-mode OVERLAY \ --merge-overlay-repeat 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);
--merge-documents https://www.myserver.com/overlaid.pdf \ --merge-mode OVERLAY \ --merge-overlay-fit 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);
--merge-documents https://www.myserver.com/overlaid.pdf \ --merge-mode OVERLAY \ --merge-disable-overlay-annotations
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.
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"
To create a keystore from certificate(s) or read information of an existing keystore such as the
keyAlias
, the Oracle Keytool can be used.
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));
--sign-pdf-key-alias "keyAlias" \ --sign-pdf-keystore-password "keyStorePassword" \ --sign-pdf-keystore-type JKS \ --sign-pdf-keystore-url http://myServer/Keystore.jks \ --sign-pdf-signing-mode SELF_SIGNED
To specify the keystoreURL
as file URL use the following syntax:
file:///path/to/Keystore.jks
If a PDF is signed via the VeriSign signing mode, a plugin for the PDF viewer is required to show the signature.
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);
--disable-font-embedding
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 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);
--add-overprint
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; }
When having small text with a background, overprinting can be very helpful to avoid white lines around the text, if the printing registration is imperfect.
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);
--add-attachments
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"));
-C config.json
With the following config.json:
{ "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"
}
]}
PDFreactor offers a number of debug files containing useful information about the conversion, e.g. logs. These can be attached to the PDF by specifying a special URL for the attachment. Please refer to for an overview of all available debug files. Note that some debug files might require additional configuration options, such as .
This chapter refers to Scripts added to the resulting PDFs, processed by the PDF-viewer. There is also:
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.
These PDF scripts must not be confused with the JavaScript that is executed while creating the PDF. PDF scripts basically use the JavaScript syntax, however, they are executed (if this feature is supported and enabled by the viewer application) at a completely different time, e.g. when opening the PDF.
The following PDF script will display a message prompt when the PDF is opened.
config.setPdfScriptAction(new PdfScriptAction() .setScript("app.alert('hello');") .setTriggerEvent(PdfScriptTriggerEvent.OPEN));
-C config.json
With the following config.json:
{ "pdfScriptAction": { "script": "app.alert('hello');", "triggerEvent": "OPEN" }}
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);
--add-preview-images
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"));
--xmp-priority HIGH \ --xmp-uri http://cdn/myXmp.xml
When attaching a custom XMP with high priority (thus overriding the PDFreactor-generated XMP), conformance such as PDF/A cannot be guaranteed.
In addition to PDF, PDFreactor, with the optional Raster Image Output, supports the following image output formats:
PNG (optionally with transparent background)
JPEG
GIF (optionally dithered)
TIFF (supports multi-page images; can use the following compression methods: LZW, PackBits, Uncompressed, CCITT 1D, CCITT Group 3 & CCITT Group 4; CCITT optionally dithered)
BMP
These can be selected using the configuration property outputFormat
, e.g.:
config.setOutputFormat(new OutputFormat() .setType(OutputType.PNG) .setWidth(512) .setHeight(-1));
--output-format-type PNG \ --output-format-width 512 \ --output-format-height -1
The later two parameters set the width and height of the resulting images in pixels. If either of these
is set to a value of less than 1
it is computed from the other value and the aspect ratio of the page.
Independent of the image type, the maximum size of any output image that PDFreactor can produce is 500 megapixels.
for the media feature -ro-output-format
, which allows
setting
styles specific for PDF or image output.
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");
--page-order "5"
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));
--output-format-type PNG \ --output-format-width 512 \ --output-format-height -1 \ --output-format-multi-image
The documentArray
property of the Result
object then returns an array of
byte arrays, each
containing an image representing one page of the document.
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));
--continuous-output-width 1024 \ --continuous-output-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.
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);
--force-grayscale-image
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")));
This chapter provides information on how to lay out documents, while focusing on the differences of the paginated layout of PDFreactor, in contrast to the continuous layout of browsers.
The document layout mostly depends on CSS but there are PDFreactor configuration properties and JavaScript functionality that may also be of use to achieve the desired results. While the common CSS properties known from browsers are supported as well, they are not covered in this chapter. Therefore an understanding of basic CSS is required.
PDFreactor renders HTML and XML documents on pages. The rules to achieve that are provided by CSS.
The document content is laid out page by page, whenever there is no more space left on a page, PDFreactor automatically breaks text and boxes to the next.
Basic page styles are provided for HTML. Page styles for XML documents need to be created based on the documents language.
Boxes around or next to breaks are subject to minor adjustments depending on the situation:
The top margin of the first block on a page or column is ignored, except for the first page or
column and for breaks forced via CSS. This difference can be
eliminated by setting the proprietary property to always
or
none
to ensure this adjustment is performed in all or no cases, respectively.
Applying styles to an element that change its formatting context, like overflow
with a value other than
visible
, may stop margins from being truncated.
A non-proprietary alternative, that also affects the layout of documents in browsers (especially relevant for multi-column) is to explicitly set specific top margins to 0.
h1 { break-before: page; margin-top: 0; } div.multiColumn > *:first-child { margin-top: 0; }
The bottom margin of the last block on a page or column is always ignored.
When a break occurs inside a block (e.g. between two lines of text in a paragraph) the block is
split into two parts. There is no border, margin or padding
at the bottom of the first part or the top of the second one. Setting the property to clone
forces the inclusion of
these borders and paddings. This does not
affect the margins.
By default no breaks can occur inside images and other replaced elements.
In cases when this is required the proprietary property
can be set to the values
auto
or avoid
to explicitly allow breaks inside block images.
To avoid too small parts of images to be split-off at the beginning or end the
and properties,
multiplied by the computed , are taken into account.
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; }
Which pages are left or right can be specified via the @-ro-preferences property
It is possible to select any page by using the prefixed CSS3 pseudo-class
:-ro-nth()
. This pseudo-class takes a function of
the form An+B
, similar to the pseudo-class :nth-child()
.
A single page can be selected (e.g. :-ro-nth(3)
selects the third page) or the
function can be used to select multiple pages. For
example, :-ro-nth(2n)
selects every second page (i.e. even pages), while
:-ro-nth(2n+1)
selects
the first and every other page (odd pages).
Note that the selected page number is independent of the page counter, which is used to display page numbers and which can be manipulated.
This pseudo-class can also be used in combination with page names. For more information see .
As the counterpart to :first
, there is the proprietary selector
:-ro-last
. It allows to select the
last page of the document.
Please note that as the content of the last page is only known after its content has been computed, there can be situations where the last page is empty. This can happen if the styles that are applied to the last page influence the layout of the page content, e.g. changing the page margins.
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; }
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.
All HTML <table>
elements have to appear on pages with the name
pageName
.
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; }
When setting a page name, a page group of this name is created automatically. Compared to named pages, page groups are more flexible and can be used to select a certain page, e.g. the first page with a name instead of all pages with that name.
While each page can have only one name, it can belong to multiple page groups, thus allowing an author to nest special pages. This means that if an element sets a page name to 'A', that page belongs to a page group of the same name, but can also belong to a group named 'B', if that group was defined by a parent element.
The following sample applies page orientation and page background color to the same page, by using two page groups.
<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; }
In contrast to named pages, it is possible to create a new group even if the page name did not change. To do so, two adjacent elements, both defining the same page name, have to be divided by a forced page break.
Another advantage of page groups, is the possibility to select certain pages belonging to a group
name. This is especially useful, if the first page of a group
should have different styles. To select the nth-page of a group, the
-ro-nth(An+B of pageName)
pseudo class is used:
Select the first page of each page group with the name pageName
.
@page :-ro-nth(1 of pageName) { background-color: lightgrey; }
For more information on the syntax of the -ro-nth() pseudo class, please see .
Text is broken whenever there is not enough space left, e.g. inside the line or on the page.
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:
Hyphenation enabled for an entire document except for paragraphs of the
noHyphenation
class.
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.
If the last line of a paragraph is also the first line of a page it is called a widow.
If the first line of a paragraph is also the last line of a page it is called an orphan.
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.)
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:
normal: This optional identifier specifies that the default rules still apply. Thus the existing rules are only extended instead of being completely overridden.
<whitelist>: These regex expression describe where break opportunities should be added.
<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.
As the strings are specified in CSS, each
backslash must be escaped. For example an
escaped opening parenthesis would require two
backslashes. One to escape the parenthesis for
regex and one to escape the backslash for CSS:
"\\("
Alternatively the character can be
placed inside brackets instead of escaping it:
"[(]"
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.
Property Value | Effect |
normal "[(]" | Allow breaks after a left parenthesis, in addition to the standard Unicode line breaking rules. |
normal / "-" | Standard Unicode line breaking rules are applied, but prevents breaks after a dash. |
normal "[.]" "\\w" | Allow breaks after a dot followed by a word character, in addition to the standard Unicode line breaking rules. |
normal / "-" "\\w" | Standard Unicode line breaking rules are applied, but prevents breaks after a dash followed by a word character. |
normal "\\w" "[(]" / "\\w" "[(][)]" | Allow breaks after a word character followed by a left parenthesis, except if a left and a right parenthesis follows, in addition to the standard Unicode line breaking rules. |
normal "[(]" / "[(]" '"' | Allow breaks after a left parenthesis, except if it is followed by a quote, in addition to the standard Unicode line breaking rules. |
"\\s" | Only allow breaks after a whitespace character. Standard Unicode line breaking rules aren't applied. |
"\\s", "-" / "-" "\\d", "-" "[a-Z]" | Only allow breaks after a whitespace character or a dash, except if a dash is followed by a digit or word character. Standard Unicode line breaking rules aren't applied. |
Long and complex rules (especially those that include wildcards) can impact the performance depending on the length of the paragraphs, so it is best practice to apply the style only to the elements that may actually need them.
Generated content does not originate from the document. It is created by CSS during the rendering process and appears in the rendered result as if it was part of the document.
The pseudo-elements ::before
and ::after
are used to generate content before
or after an element. The
actual content is created with the property.
To create generated text, set a String as value of the content
property.
Generated Text on an HTML <div>
element.
<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:
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 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.
A chapter heading for HTML <h1>
elements using Counters and Generated Text.
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.
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 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.
In case the document does not provide elements to use Running Elements and Generated Content does not suffice, it is possible to add elements to the document with JavaScript to be able to use Running Elements.
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.
An HTML <footer>
element at the start of the document used as page footer in
all pages.
<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.
Two Running Elements at the start of the document with the same name. The first appears on page one, the second on every page thereafter because it is the latest Running Element of the name.
<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.
An HTML <footer>
element at the end of the document is used as Running
Element. The page footer displays it in the last page
only, as it is not available earlier.
<body> ... <footer>...</footer> </body>
footer { position: running(footerIdentifier); } @page { @bottom-center { content: element(footerIdentifier); } }Notice how the style does not differ from the one used in the first example of this chapter. This shows how much influence the position of a Running Element is inside the document has.
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.
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.
The xhtml()
function is a proprietary extension of CSS and will only work for
RealObjects products.
/* 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.
When using the xhtml()
function in non-HTML5 documents (e.g. XHTML inside the head
in a <style> element) the entire CSS
needs to be wrapped in an XML comment.
<!-- @page { @top-center { content: xhtml("<table>...</table>"); } } -->
Additional features for are available within Page Margin Boxes.
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); } }
For XML documents you can define the Page Counter as follows.
@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 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.
A Named String headingString
created from the heading's text with the function
content()
and
read with the string()
function from the page header:
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.
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.
PDFreactor only resolves internal links referring to an anchor in the same input document, see the chapter for more information.
The target-counter()
function is used inside the content
property the
same way a counter()
function would be used. It receives a URL to the referenced
location and the name of the counter as identifier. It may
receive an optional third argument to define the output style of the counter, just like the
counter()
function.
Cross-references created from an HTML hyperlink to a chapter heading with a numbering.
The Cross-reference is declared with generated text and target-counter()
functions to retrieve the page and chapter numbers.
... <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); }
Assuming the referenced chapter would render on page 5 as the third chapter, the cross-reference would read:
For more information, see Chapter III on page 5.
The target-text() function is used inside the content
property in a
similar way as the target-counter()
function is used. It receives a URL to the
referenced location and takes one of these four
keywords to specify the text to retrieve:
content
- Retrieves the textual content of the element. This is the default
keyword if no keyword is present.
first-letter
- Retrieves the first letter of the element's textual content.
The following example shows a cross-reference that references a heading and shows its before Generated Content and text:
a[href]{ content: target-text(attr(href), before) " " target-text(attr(href), content); }
target-text()
makes it easy to retrieve the before Generated Content of an
element, which may include its numbering. This
method does not require any knowledge about how this before Generated Content is created but
it also does not allow to rebuild it into something
different.
If the before Generated Content of an element is "2.1" and the page header should be
"Chapter 2, Section 1" the target-counter()
function provides the
necessary means to retrieve all
the individually.
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;The text content of the element that the style applied to, will appear in the footnote area at the bottom of the page. The footnote area of pages can be styled via CSS using the
footnote
at-rule.
HTML (snippet)
<p>This is a CSS<span class="footnote">Cascading Style Sheet</span> generated footnote.</p>
CSS
.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: footnoteBy default, this counter numbers the footnotes sequentially for the entire document. To number footnotes on a per-page basis, the counter has to be reset on every page, using the following style:
@page { counter-reset: footnote; }
PDFreactor currently does not support nested footnotes.
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, 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.
HTML (snippet)
<p>This is the normal page content.<span class="sidenote">This is the sidenote</span></p>
CSS
.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; }
PDFreactor currently does not support nested sidenotes or footnotes inside sidenotes.
When sidenotes are too close together, the upper sidenotes will generally push the lower
sidenotes down to avoid overlapping. However, a sidenote can be prioritized so that it tries to
prevent overlapping by pushing previous sidenotes up, thus maintaining its intended position.
This can be done for baseline
, container-start
and
container-end
alignments by appending the keyword strict
.
.sidenote { float: -ro-sidenote(right); -ro-sidenote-align: baseline strict; }
Note that a sidenote with strict alignment may still be moved up or down to prevent overlapping if there is not enough space for all sidenotes.
When aiming for a certain style, it may be useful to offset the position of sidenotes. This can
be done for baseline
, container-start
and container-end
alignment by using the CSS property -ro-sidenote-offset. It allows to shift a
sidenote up or down by a specified length (with negative length shifting up). Percentage values
are resolved with the sidenote's border-box height.
.sidenote { float: -ro-sidenote(right); -ro-sidenote-align: container-start; -ro-sidenote-offset: 5mm; }
It is possible to define an avoid area via an element in the page content by using the CSS property -ro-sidenote-avoid. If possible, the placement of sidenotes next to that element is avoided. An additional parameter allows to specify which box is used to determine the avoided area (e.g. the margin or content box). This is useful if the element should overflow into the sidenote area in order to use the maximum avaiblable space on the page. However, sidenotes may still end up overlapping if there is not enough space left.
Although it is uncommon, in certain situations it may be useful to have calls and markers, similar to footnotes. They are not used by default, but pseudo-elements are provided to create them. A call is generated in the content where the sidenote originates and a marker is placed just before the sidenote content.
By creating and using a global counter for sidenotes, it is possible to number them, thus showing exactly what each sidenote refers to.
HTML (snippet)
<p>This is the normal page content.<span class="sidenote">This is the sidenote</span></p>
CSS
: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;
}
Note that the numbering of the sidenotes is in DOM order, so depending on the layout (e.g. multi-column) or the vertical alignment, they are not necessarily sorted by that numbering when appearing in the sidenote area.
The sidenote area is the container in which the sidenotes are positioned. Each page can have a
left and a right one. Styles can be applied to sidenote areas by selecting them via the at-rule
@-ro-sidenote
inside a page-rule, similar to how page margin boxes are selected.
However, using this at-rule alone will select both sidenote areas. To select
only one area, a pseudo-class has to be appended:
Psuedo Class | Description |
:left |
Selects the sidenote area that is visually on the left or right. |
:right |
|
:verso |
Selects a different sidenote area depending on the text direction of the document. Verso is left in left-to-right documents and right in right-to-left documents. Recto is right in left-to-right documents and left in right-to-left documents. |
:recto |
|
:inside |
Selects a different sidenote area depending on the side of the page, which is useful when having different styles for left and right pages. Inside is right for left pages and left for right pages. Outside is left for left pages and right for right pages. |
:outside |
Note that the styles set on the sidenote area are not inherited to the sidenotes themselves.
They still inherit from their parent elements in the DOM. Making the sidenote styles completely
independent from the styles of the rest of the document can be achieved by applying
all:initial
:
.sidenote {
/* Prevent style inheritance */
all: initial;
float: -ro-sidenote(outside);
}
When setting the size of a sidenote area, there are several special behaviors that have to be taken into account. Firstly, some properties cannot be applied. The height of the area is always determined via the height of the page content. And as its width is fixed and will not be changed by its content, the minimum and maximum size properties are ignored.
Secondly, the width property is handled a bit differently. A width of auto
is
resolved to a sidenote area with an outer width that is exactly as wide as the page margin
of the respective side. This means that the width that is available to the page content
remains unchanged.
Percentage widths are relative to that page margin width defined by its page rule:
@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%; } }
If a sidenote area is larger than the respective page margin, the page content width is reduced by that difference, as if the page margin was increased. However, the page margin boxes themselves remain unchanged and still use the margin widths that have been defined in their respective page rule.
Note that when specifying both areas on the same page, then neither of them may occupy more than half of the page width or else they may overlap with the page content.
When defining a sidenote area that should always be on the outside of a page, their margin
or border styles also have to depend on the page side. This can be achieved by defining
different @-ro-sidenote
rules for each page side:
@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;
}
}
The styles above create sidenote areas on the outside of all pages, with a margin to the page edge and a border towards the page content. However, the same can be achieved far easier by the special behavior of logical properties on sidenote areas.
Under normal circumstances logical properties are mapped to their physical counterparts depending on the text direction. However, logical properties set on sidenote areas are resolved depending on whether the area is on the left or the right side of a page. The "inline start" properties are resolved to the outside side (i.e. right on right pages and left and left pages) and "end" properties are resolved to the inside side (i.e. left on right pages and right on left pages). Imagine the area growing from the page edge towards the page content.
@page { margin: 2cm; @-ro-sidenote:outside { width: 3cm; background-color: #eee; border-inline-end: 1mm solid grey; margin-inline-start: 2cm; } }
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; }
In order to hint to the next page number, the proprietary function -ro-counter-offset is used in this sample to modify the current page number by one.
PDFreactor is capable of applying two dimensional transformations on elements with the property, which makes moving, rotating and scaling document content possible.
Transforms do not have an impact on the document layout, e.g. content with scaled up size will not push other content away to prevent overlapping.
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
Key | Description | Default |
angle |
The angle in degrees at which the header will be rotated. Should be between
-90 and 90
|
45 |
width |
The width that the header cells should have after the transformation, e.g.
"20pt" .
|
"auto" |
firstCol |
Whether to prevent the first column from being transformed. | false |
lastCol |
Whether to prevent the last column from being transformed. | false |
footer |
Whether to create a <tfoot> element from the last row in the table.
Has no
effect if the table already contains a <tfoot> .
|
false |
The content of a document can be arranged in columns with elements like images or titles spanning through all columns if desired. Elements are laid out in a way similar to pages, text and boxes will break whenever no space is left in a column.
Multi-column layout is often used in print products like newspapers or magazines, it is intended to reduce the line width to make text easier to read.
The following box shows how text flows in a three-column layout. The paragraphs are numbered to better visualize the effect of multi-column layout.
[1] Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla in libero turpis. Sed sed dolor diam, eu dapibus quam. Quisque ut nulla purus, iaculis sollicitudin erat. Nullam dictum suscipit porttitor.
[2] Aliquam aliquam elementum elementum. Donec vel odio nec diam ullamcorper ultricies vel sit amet elit. Cras non aliquet lectus.
[3] Donec sollicitudin lorem placerat est condimentum rutrum. Fusce tempor cursus rutrum. Duis mattis mattis sapien. Phasellus tempus iaculis tellus sed vestibulum.
[4] Etiam faucibus consectetur augue, sit amet interdum elit dapibus at.
To create a multi-column layout inside an element add either the property or or both. By adding them the element becomes a multi-column element.
The column-count
property defines the number of columns inside the element. Any number
greater than 1 will create a multi-column
layout. The column-count
property is especially useful if the actual width of the columns
is not as important as the number of columns.
Alternatively, the column-width
property can be used to specify a minimum width for the
columns. Based on this width the final column count is computed,
thus the resulting column widths are likely larger than the specified value.
/* define two columns */
div.twoColumns { column-count: 2; }/* define columns with a width of 2in */
div.twoInchColumns { column-width: 2in; }
By default, PDFreactor aims to balance the content of columns so that the content of all individual columns is equally long, if possible. This has the effect of keeping the height of each column at the possible minimum, which automatically determines the height of the multi-column element as a whole if it wasn't defined by a height property or attribute.
This behavior can also be modified to fill columns sequentially. In this case, the columns are filled until no more space is available in one column and the rest of the content needs to be moved to the next column. With this behavior a multi-column element whose height is not restricted will take up all the remaining space inside the multi-column-element, up to the remaining space available on the page until it breaks to another column.
The filling behavior can be controlled with the property:
/* sequential filling behavior */
div.sequentialFill { column-fill: auto; }/* balanced filling behavior */
div.balancedFill { column-fill: balance; }
A defined height on the multi-column element will be used for an element, regardless of the filling behavior. If there is less content than there is space inside the multi-column element a balanced filling behavior will create shorter columns, leaving space at the bottom of the multi-column element. Sequential filling behavior may not have enough content to fill all the columns, thus columns may be left empty. If there is more content than there is space inside the multi-column element, the multi-column element will create a page break and continue on the next page, at the first column.
Usually elements inside a multi-column element are laid out one after another in columns as defined by the filling behavior. Some elements, however, may require a certain behavior when inside columns.
There are elements that are required to span all columns inside the multi-column element instead of only one. Headings, pictures or tables are the most common examples. To have an element span all columns the property is used.
/* a heading that spans all columns */
h1 { column-span: all; }/* a table in a single column */
table { column-span: none; }
To add some visual appeal to the multi-column element borders, backgrounds and padding can be used. Beside these standard styles multi-column elements can also receive additional styles for the space between columns.
To visually separate columns it is possible to define the gap width. Gaps can be considered as padding between columns. To define the gap width for a multi-column element the column-gap property is used.
/* a gap of 0.25in */
div.multiColumn { column-gap: 0.25in; }
In addition to the gap a rule can be added between the columns as additional visual aid for separating columns. To define rules for a multi-column element the property either the shorthand or the individual properties , or can be used.
/* a solid black rule with 0.1in width*/
div.multiColumn { column-rule-width: 0.1in; column-rule-style: solid; column-rule-color: black; }/* the same definition as shorthand */
div.multiColumn { column-rule: 0.1in solid black; }
With CSS it is possible to align lines of text to invisible grids in the document. This greatly improves readability of duplex printing or for documents with multi-column layouts. Lines remain at the same position on every page, thus keeping a vertical rhythm which is very beneficial to the reading experience.
The below images show how snapping to the line grid works and how it improves readability in a text with two columns (the line grid is visualized by the dotted lines).
Snapping to grid can be enabled by using the CSS property . In addition to snapping to the baseline of the grid, it is also possible snap line boxes to the center of two of the grid's lines. The latter may be beneficial for text that contains small and large font sizes because the space in the grid is used more efficiently.
/* snapping to baseline */
p { -ro-line-snap: baseline; }/* snapping between grid lines */
p { -ro-line-snap: contain; }
Line grids are created automatically. Normally, one line grid is created for the root element on each page and is then used by all its block-level descendants. It is also possible to create a new line grid for a block using its own font and line height settings. This is very useful for multi-column containers as it might be undesirable for such a container to use its parent's grid. A new grid can be created with the following style declaration, using the CSS property :
div { -ro-line-grid: create; }
When using Page Floats and line grids, make sure that top floated elements are also set to snap to the grid, otherwise they may push the text below them downwards, so that the lines are no longer aligned with the grid.
Also avoid mixing different line grid settings with page floats, as on each page only the last page float that snaps to a grid can be taken into account, so using different line grids may also lead to misaligned text.
Applying styles to an element that change its formatting context, like overflow
with a value other than
visible
, may change the position of the grid's baselines.
Regions are containers for document content similar to pages or columns, but they can be positioned individually. In contrast to automatically created pages and columns, regions are based on block elements from the document, which presents them with more styling options.
Regions belong to a region chain, that connects them and tells how their contents flows from one to another. The content of a region chain is called the named flow and elements can be added to a named flow to be displayed in regions.
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.
A region element will not have its subtree rendered. It either displays content from a named flow or nothing.
A chain of two regions defined for two HTML div
elements with IDs
region1
and region2
.
#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.
A region does not influence the style of the content it contains. No style is inherited from a region into the displayed named flow and style that would influence the content of an element has no effect on a region's content.
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.
Creation of a named flow for two HTML <article>
elements while an HTML
<section>
element from one of the articles is moved to a different named flow.
<article>...</article> <article> ... <section id="info">...</section> </article>
article { -ro-flow-into: articleNamedFlowName; } section#info { -ro-flow-into: infoNamedFlowName; }
The content of a named flow may be rendered inside regions, but it still inherits style and computes its style the same way it would as if it did not appear inside a region.
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.
Although PDFreactor performs automatic breaks between boxes for pages, columns and regions, it is often necessary to add explicit breaks in certain situations or breaks should be avoided to keep content together where it belongs together. This chapter explains how both can be achieved.
PDFreactor provides styles for HTML that influence the break behavior for certain elements like headings. Break Styles for XML documents need to be created based on the document language.
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.
A manual page break before an HTML <h1>
element, used to make a chapter start
on top of a new page.
h1 { break-before: page; }
A manual page break before an HTML <h1>
element, that makes the chapter start
on a right 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; }
PDFreactor also supports the CSS 2.1 properties page-break-before
and
page-break-after
.
They are resolved as shorthands for break-before
and break-after
.
To manipulate the break behavior inside a box, the property is used. It specifies whether breaking should be avoided inside the box or not.
Avoid breaks inside an HTML <div>
element.
div { break-inside: avoid; }
PDFreactor also accepts the CSS 2.1 property page-break-inside
and resolves it as
shorthand
for break-inside
.
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
Page floats are an extension of regular floats, also called inline floats, as they float in inline direction, i.e. left and right. Page floats on the other hand allow to float up and down, to the top or the bottom of a fragmentation container (page, column or region). If there is not enough space left, the page float is moved to the next fragmentation container, e.g. to the top/bottom of the following page, while the rest of the content continues on the current page.
The current implementation of page floats does come with some limitations:
The normal content does not flow to the sides of the page float. Basically, the page float area always consumes the complete width of the corresponding fragmentation container, even if a page float itself has a smaller width.
The page float always flows in the current fragmentation container. For example, a page float originating in a multi-column, will always stay in a column and is not moved to the level of the page.
The content of a page float cannot be fragmented, meaning that if it becomes larger than a page, it will overflow instead of being split to the next page.
The CSS property float has been extended with the values -ro-top and -ro-bottom to enable page floats. To set the distance between two page floats of the same side or to the corresponding edge of the page, the new property -ro-float-offset can be used.
With this sample, elements with the class pageFloatTop
float to the top of their page
with a gap of
5 mm to the page margin areas at the top.
.pageFloatTop { float: -ro-top; -ro-float-offset: 5mm; }
When inline floats (left or right floated) precede the page float, the inline float may overflow the page. The same may happen in wrapped column flex items. Basically, when blocks of content are next to each other, problems can arise when the page float does not originate from the first one. This is a known issue that will be addressed in a future version.
PDFreactor provides additional means for professional printing that allow to specify oversized pages, a bleed area and marks for cutting sheets to the final page size and color proofing.
Page boxes are used to specify the page geometry, especially in professional printing. PDFreactor supports the TrimBox, MediaBox, BleedBox, CropBox and ArtBox.
The TrimBox defines the size of the final print result, the final page. It contains the page content.
The size of the TrimBox is defined equivalent to the page size, as mentioned in chapter , using the property.
The value of the size
property also automatically specifies the TrimBox.
size: A4 portrait;
In prepress, a printed document can contain more information than just the actual content in the TrimBox (e.g. bleed or ).
As this information does not belong to the print result and instead needs to be printed around it, a print sheet larger than the print result is needed. The MediaBox defines the size of the print sheet.
Special oversize formats are used as print sheet in such cases. For DIN Deutsches Institut für Normung, in English: German Institute for Standardization, Germany's ISO member body. standard-based formats, the matching oversize formats to the A series are the DIN-RA and DIN-SRA formats. An overview of all supported page sizes can be found in the Appendix
The property is used to specify the media size.
The document should be printed in DIN-SRA4 and the MediaBox is set to this size
-ro-media-size: SRA4;
The MediaBox is the largest of all 5 page boxes and contains all others which can be smaller or equal than this box.
The BleedBox contains the TrimBox and is slightly larger. Content from the TrimBox may "bleed" into the BleedBox where it is still painted.
This is necessary for content that should reach to the edge of the print result. It prevents having unprinted areas due to unprecise trimming of the printed sheet.
The size of the BleedBox is defined as a width that adds to the TrimBox' size on all four sides. Common bleed values are 3-5 mm or 1/8 inch.
Setting the bleed size can be achieved by using the property bleed.
A bleed width of 3mm around the print result. The Bleed Box determines it's size from the TrimBox and this width.
bleed: 3mm;
By default, any content is cut off at the end of the bleed box. If you need content to overflow into the media box, you can use the -ro-page-clip CSS property to adjust this behavior.
The CropBox defines the complete area of the document that should be displayed on screen or printed out.
The crop size can be defined using the property .
The crop size can be set to a specific page size format (like setting the trim size) or to one of
the page boxes. It is set to none
by default.
The CropBox is set to match the MediaBox.
-ro-crop-size: media;
The ArtBox is used to define a specific area inside which the page's content is located.
Using the property , the ArtBox can be set to a specific
page size or
one of the page boxes. It is set to none
by default.
When generating a PDF/A conformant file (see PDF/A
conformance), the ArtBox must not to be defined, so
the property must be set to none
.
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;
Using the proprietary property
allows content with position: absolute
to be positioned relative to any
page box of its page.
This is especially useful to place decorative content relative to the bleed box, thus
making it exceed the trim box so bleed is properly utilized.
@page {
bleed: 3mm;
-ro-media-size: SRA4 portrait;
-ro-crop-size: media;
marks: trim bleed registration;
@top-right-corner {
content: counter(page);
vertical-align: top;
text-align: right;
padding: 1cm;
position: absolute;
top: 0;
right: 0;
width: 5cm;
height: 5cm;
background-image: radial-gradient(at 100% 0%, lightblue 0%, white 50%);
-ro-position-origin: -ro-bleed-box; /* Position in the bleed box of the page */
}
}
Leaders are often used to draw a visual connection between an entry in a table of contents or similar structures, and a corresponding value.
In CSS, drawing leaders is accomplished via the use of the leader()
function. This function
accepts the following values:
dotted
solid
space
<string>
A leader may be added using the content property, and can be combined freely with other generated content such as counters.
a.toc_ah2::after { content: leader(dotted) " " target-counter(attr(href), page); }
This may result in a display such as:
A table of contents can be inserted into a document to generate a list of the chapters or other important sections in the document.
This feature is usually used together with cross-references to add links to a table of contents. With the addition of counters, it can be complemented with the page numbers of the linked chapters.
The createTableOfContents()
function provided by allows to insert
a
table of contents that is generated from given elements.
The table of contents requires certain styles to work properly. These styles are included in the
awesomizr.css and should be added either to the document or by
using the userStyleSheets
configuration property of the PDFreactor API.
The table of contents is inserted as an HTML div
element with the class
ro-toc
. Inside this div
can be two headings (document title and a heading for
the table of contents with the class ro-toc-heading
)
and the div
elements with links to the pages and a class depending on the level of the
referenced element (ro-toc-heading1
,
ro-toc-heading2
, ...)
The level of a TOC entry is determined by the position of its selector in the elements
array.
Awesomizr.createTableOfContents({elements: ["h1", "h2", "h3"]});
The function's optional parameter is an object with several options:
Key | Type | Description | Default |
insertiontarget |
string |
CSS selector string of the element where the table of contents should be inserted. | "body" |
insertiontype |
string |
Specifies where exactly the table of contents should be inserted:
|
"afterbegin" |
elements |
array |
An array of the CSS selector strings of elements that should be added to the table of
contents. Each TOC entry gets a class name
based on the index of the corresponding selector in this array, e.g. by default the h2
entries have the class ro-toc-level-2 .
|
["h1", "h2"] |
toctitle |
string |
The title of the table of contents. If an empty string is set, no title is inserted. | "Table of Contents" |
disabledocumenttitle |
boolean |
Whether the document title should NOT be inserted before the table of contents. | false |
text |
function |
By default, the text for the entries of the TOC is the text content of the element matching
the specified selector. Alternatively,
you can specify a function, the return value of which will be used as text for the
respective entry. The element representing the entry is passed as an
argument to the function. Returning false will skip the entry entirely and not
include it in the TOC.
|
null |
Simple table of contents created with Awesomizr based on HTML <h2>
elements.
<link href="css/awesomizr.css" type="text/css" rel="stylesheet" /> <script type="module"> import * as Awesomizr from "./awesomizr.js"; Awesomizr.createTableOfContents({elements:['h2']}); </script> ...
Awesomizr.createTableOfContents({ elements: ['img'], text: function(elem) {// the entry text should be the image's alt text
let txt = elem.alt; if (txt) { return txt; }// skip images without alt text
return false; } });
Alternatively, a table of contents can also be created by using XSLT. Both approaches are demonstrated by the two versions of the "Children's Novel" sample. You can find them in the PDFreactor/samples/novel directory.
For some documents parts of the content are too wide to fit the pages. In most cases this is caused by
HTML documents containing fixed widths intended for screens,
e.g. 1024px
for the main container element.
While the best solution is adding a print style sheet to override the critical styles with relative widths, such content can also be shrunk automatically without changing the source document or adding specific styles.
There are two different shrink-to-fit functionalities available in PDFreactor,
pixelsPerInchShrinkToFit
and . These are non-exclusive and are applied in the
aforementioned order.
Shrink-to-fit is only recommended when you need to force content into the boundaries of pages. For high-fidelity print output, these modes should not be used.
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);
--pixels-per-inch-shrink-to-fit
The pixels per inch can also be specified manually.
This property must be part of the @page
rule affecting the first page:
Page content scaling, if used, always applies to all pages equally. It cannot be applied to only a subset pages or page groups.
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.
You can control the vertical position of the scaling effect with the CSS
property and its usual values:
start
, end
, center
, baseline
(default) and
stretch
.
The value stretch
won't scale down the text vertically, instead the text is skewed
to keep its
original height.
.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; }
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.
Usually, the page order of a PDF is only determined by its input document. However, using the
configuration property pageOrder
, the page order can be set by providing a
string parameter.
For ease of use the following constants are available for the most common cases of page orders:
REVERSE
— The page order is reversed.
EVEN
— All even pages are moved before all odd pages.
ODD
— All odd pages are moved before all even pages.
BOOKLET
— All pages are ordered as in a booklet. To be used with PagesPerSheetDirection.RIGHT_DOWN
.
BOOKLET_RTL
— All pages are in right-to-left booklet order. To be used with PagesPerSheetDirection.RIGHT_DOWN
.
Instead of using a predefined order the parameter can also provide a custom order as comma-separated list of page numbers and ranges:
"x,y,z"
— New page order x, y, z.
"x..y"
— All consecutive pages from x to y.
"x*n"
— The page x is repeated n times.
"-x"
— Negative page numbers count backwards beginning from the last page and can
be used in combination with all of the above.
"A"
— All pages of the document. Same result as "1..-1".
config.setPageOrder("2,5,6*2,8..10,-1,-2");
--page-order "2,5,6*2,8..10,-1,-2"
The page order shown above results in a PDF having the following page numbers from the original document, assuming it has 20 pages total: 2, 5, 6, 6, 8, 9, 10, 20, 19.
"2"
— Page 2.
"5"
— Page 5.
"6*2"
— Page 6 two times.
"8..10"
— Pages 8 to 10.
"-1"
— The last page, here page 20.
"-2"
— The second to last page, here page 19.
On the Python command line instead of --pageOrder "-1..1"
we recommend using
--pageOrder="-1..1"
to
specify the page order.
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");
--merge-documents https://www.myserver.com/insert1.pdf https://www.myserver.com/insert2.pdf \ --merge-mode ARRANGE \ --page-order "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.
Instead of containing only one page of the input document per PDF page, multiple pages of the input document can be displayed on one sheet.
The pages will be arranged in a grid on the sheet. The number of columns and rows of this grid are user-defined.
To utilize Pages Per Sheet use the configuration property pagesPerSheetProperties
.
The properties rows
and cols
define the corresponding number of pages that get
laid out on a single page.
Their values are required. The values for sheetSize
, sheetMargin
and
spacing
can be set as CSS width values. direction
defines in which way the single pages are
ordered.
There are the following options to set a direction:
PagesPerSheetDirection.RIGHT_DOWN
— The single pages are ordered from left to right
and top to bottom. This is the default
value.
PagesPerSheetDirection.RIGHT_UP
— The single pages are ordered from left to right
and bottom to top.
PagesPerSheetDirection.LEFT_DOWN
— The single pages are ordered from right to left
and top to bottom.
PagesPerSheetDirection.LEFT_UP
— The single pages are ordered from right to left
and bottom to top.
PagesPerSheetDirection.UP_RIGHT
— The single pages are ordered from bottom to top
and left to right.
PagesPerSheetDirection.UP_LEFT
— The single pages are ordered from bottom to top
and right to left.
PagesPerSheetDirection.DOWN_RIGHT
— The single pages are ordered from top to bottom
and left to right.
PagesPerSheetDirection.DOWN_LEFT
— The single pages are ordered from top to bottom
and right to left.
config.setPagesPerSheetProperties(new PagesPerSheetProperties() .setCols(2) .setRows(2) .setSheetSize("A4 landscape") .setSheetMargin("2.5cm") .setSpacing("2cm") .setDirection(PagesPerSheetDirection.RIGHT_UP));
--pages-per-sheet-properties-cols 2 \ --pages-per-sheet-properties-rows 2 \ --pages-per-sheet-properties-sheet-size "A4 landscape" \ --pages-per-sheet-properties-sheet-margin "2,5cm" \ --pages-per-sheet-properties-spacing "2cm" \ --pages-per-sheet-properties-direction RIGHT_UP
Disabled Features. Bookmarks, comments, links, and tags will be automatically disabled when using pages-per-sheet mode.
A Booklet is a set of folded pages meant to be read like a book. PDFreactor supports creating Booklets by combining the functionality with the feature.
It orders the pages in booklet or rtl booklet page order and places two of these pages on each sheet, rotated by 90 degrees and side-to-side.
A configuration property allows to configure the page size and margins of the container page as well as to use the default booklet page order or a reversed order:
config.setBookletMode(new BookletMode() .setSheetSize("A4 landscape") .setSheetMargin("1cm") .setRtl(false));
--booklet-mode-sheet-size "A4 landscape" \ --booklet-mode-sheet-margin "1cm"
If you don't want to produce N-up output right away or if you plan duplex printing, it is sometimes desirable to produce a PDF that always has an even page count or a page count which is a multiple of N for the N-up layout you want to achieve down the line. To automatically append pages to the PDF to achieve such a page count, you can use the Awesomizr JavaScript library.
The autoFillPages()
function dynamically inserts pages until the total page count is a
multiple of the indicated number.
This function takes one object as optional parameter with the following properties:
Name | Type | Description | Default |
multiple |
number | Pages will be filled up until the page count is a multiple of this property. | 2 |
target |
string | The filler page objects will be inserted as new children of the element matching this selector. | "body" |
template |
function | A function that must return an HTMLElement which will be used as the filler pages. Returning null or undefined skips the page. If no function is specified, a custom element is inserted. The function receives the following three arguments: The current index of the inserted filler page (starting at 0), the total number of filler pages to be inserted, the total (original) page count of the document. |
The empty pages that are inserted this manner can be styled further. The pages have the
roFillerPage
name
and the HTML elements that create them have the roFillerPage
class.
By default, lengths specified in pixels (i.e. via the CSS unit px
or HTML attributes) are
converted to physical lengths at a rate of 96
pixels per inch. With the configuration property pixelsPerInch
this can be changed, e.g.:
config.setPixelsPerInch(120);
--pixels-per-inch 120
Increasing the pixels per inch can be used to shrink documents that would be to wide for pages due to fixed widths originally intended for screens.
Finding the optimum value can be automated using shrink to fit.
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");
--document-default-language "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.
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; }
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 "International Sample" document in the PDFreactor package demonstrates the usage of these properties and values. It can be found in the PDFreactor/samples/i18n directory.
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:
Property | LTR | RTL |
padding-inline | padding-left padding-right | padding-right padding-left |
padding-inline-start | padding-left | padding-right |
padding-inline-end | padding-right | padding-left |
border-inline-start | border-left | border-right |
border-inline-end | border-right | border-left |
border-inline-start-color | border-left-color | border-right-color |
border-inline-end-color | border-right-color | border-left-color |
border-inline-start-style | border-left-style | border-right-style |
border-inline-end-style | border-right-style | border-left-style |
border-inline-start-width | border-left-width | border-right-width |
border-inline-end-width | border-right-width | border-left-width |
border-start-start-radius | border-top-left-radius | border-top-right-radius |
border-start-end-radius | border-top-right-radius | border-top-left-radius |
border-end-start-radius | border-bottom-left-radius | border-bottom-right-radius |
border-end-end-radius | border-bottom-right-radius | border-bottom-left-radius |
margin-inline | margin-left margin-right | margin-right margin-left |
margin-inline-start | margin-left | margin-right |
margin-inline-end | margin-right | margin-left |
inset-inline | left right | right left |
inset-inline-start | left | right |
inset-inline-end | right | left |
Property | LTR | RTL |
inline-start | left | right |
inline-end | right | left |
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");
--media-types "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 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"));
-C config.json
With the following config.json:
{ "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.
Feature Name | Description | min-/ max- |
Page Characteristics Media Features | ||
---|---|---|
aspect-ratio |
Calculated from width and height . The value is a fraction,
e.g. 16/10 .
The default value is derived from width and height .
|
Yes |
device-aspect-ratio |
Calculated from the device-width and device-height . The value
is a
fraction, e.g. 16/9 . The default value is derived from
device-width and device-height .
|
Yes |
device-height |
The height of the rendering surface. The default value is 297mm (i.e. A4
height) |
Yes |
device-width |
The width of the rendering surface. The default value is 210mm (i.e. A4
width). |
Yes |
display-mode |
Represents certain aspects of how a web application shows the content. This is not
applicable for PDFreactor. The default value is fullscreen .
|
No |
height |
The height of the targeted display area. The default value is 257mm (i.e.
A4 height with 2cm top and bottom margin). |
Yes |
horizontal-viewport-segments |
The number of horizontal segments that the display has. This is not
applicable for PDFreactor. The default value is 1 .
|
No |
orientation |
Is portrait if height is greater than or equal to
width ,
or landscape otherwise. The default value is derived from device-width and
device-height.
|
No |
overflow-block |
How overflowing content in block (i.e. vertical) direction is handled when it is larger
than the viewport. The default value is paged , except when enabling
continuous
output (see ), in which case it is set to
none .
|
No |
overflow-inline |
How overflowing content in inline (i.e. horizontal) direction is handled when it is
larger
than the viewport. The default value is none .
|
No |
vertical-viewport-segments |
The number of vertical segments that the display has. This is not
applicable for PDFreactor. The default value is 1 .
|
No |
width |
The width of the targeted display area. The default value is 170mm (i.e. A4
width with 2cm left and right margin). |
Yes |
Color Media Features | ||
color |
The number of bits per color component of the output device. The default value is
8 ,
except if the output was set to forceGrayscaleImage (see )
in which case it is set to 0 .
|
Yes |
color-gamut |
Describes the approximate range of colors that are supported by the UA and output
device.
This is not applicable for PDFreactor. The default value is srgb .
|
No |
color-index |
The number of entries in the color lookup table. The default value is 0 ,
except if
the output format was set to gif in which case it is 256 .
|
Yes |
dynamic-range |
Combination of brightness, contrast ratio, and color depth that are supported by the
user agent and the output device. This is not applicable for PDFreactor. The default
value is standard .
|
No |
inverted-colors |
Indicates whether the content is displayed normally, or whether colors have been
inverted.
The default value is none .
|
No |
monochrome |
The number of bits per pixel in a monochrome frame buffer. The default value is
0 ,
except if the output was set to forceGrayscaleImage (see )
or to a monochrome output format (certain tiff variants). In the first case
it is set to 8 and in the latter it is set to 1 (which means
there
is only either black or white, but no grey).
|
Yes |
Display Quality Media Features | ||
environment-blending |
Used to query the characteristics of the user’s display so the author can adjust the
style of the document. The default value is opaque .
|
No |
grid |
Whether the device is grid or bitmap based. The default value is 0 . |
No |
resolution |
The device resolution in dpi , dpcm or dppx .
This also defines the value of the window.devicePixelRatio property
available from JavaScript.
|
Yes |
scan |
Describes the scanning process of some output devices. This is not applicable for
PDFreactor. The default value is progressive .
|
No |
update |
Used to query the ability of the output device to modify the appearance of content once
it has been rendered. The default value is none .
|
No |
-ro-output-format |
(proprietary) The output format of the conversion, either pdf ,
image or viewer (i.e. PDFreactor Preview app). This value can
not be overridden via the API configutation.
|
No |
Interaction Media Features | ||
any-hover |
Whether there is any available input device that allows the user to hover over elements.
This is not applicable for PDFreactor. The default value is none .
|
No |
any-pointer |
Whether there is any available input mechanism that is a pointing device, and if so, how
accurate is it. This is not applicable for PDFreactor. The default value is
none .
|
No |
hover |
Whether the primary input device allows the user to hover over elements. This is not
applicable for PDFreactor. The default value is none . |
No |
nav-controls |
Whether there is a user interfaces that provides navigation controls (e.g. moving back
in
session history and changing the URL). The default value is none .
|
No |
pointer |
Whether the primary input mechanism is a pointing device, and if so, how
accurate is it. This is not applicable for PDFreactor. The default value is
none .
|
No |
Video Media Features | ||
video-color-gamut |
Describes the approximate range of colors that are supported by the UA and output
device's video plane.
This is not applicable for PDFreactor. The default value is srgb .
|
No |
video-dynamic-range |
Represents the combination of max brightness, color depth, and contrast ratio that are
supported by the UA and output device's video plane.
This is not applicable for PDFreactor. The default value is standard .
|
No |
Scripting Media Features | ||
scripting |
Detects whether JavaScript is available. The default value depends on whether JavaScript
is enabled. It is either initial-only or none .
|
No |
-ro-scripting |
Is initial-only when JavaScript is explicitly enabled, none
otherwise. This value can not be overridden via the API configutation.
|
No |
User Preference Media Features | ||
forced-colors |
Tells whether the user-agent enforces a limited color palette. The default value is
none .
|
No |
prefers-color-scheme |
Reflects whether the user prefers light or dark color themes. The default value is
light .
|
No |
prefers-contrast |
Detects if the user has requested more or less contrast in the page. The default value
is no-preference .
|
No |
prefers-reduced-data |
Detects if the user has a preference for being served alternate content that uses less
data for the page to be rendered. The default value is no-preference .
|
No |
prefers-reduced-motion |
Detects if the user has requested the system minimize the amount of animation or motion
it uses. The default value is reduce .
|
No |
prefers-reduced-transparency |
Detects if the user has requested the system minimize the amount of transparent or
translucent layer effects it uses. The default value is no-preference .
|
No |
PDFreactor does not take account of the values of CSS properties in the document when
determining the values of media features. For example, setting the
page height to 50mm
will have no effect on a media query that tests the
max-height
of the document. Instead, the media features
supported by PDFreactor all have default values (for details see the
Configuration.MediaFeature
class in the PDFreactor API
documentation). These default values can be overridden through the PDFreactor API, with some
exceptions that are determined automatically.
PDFreactor allows setting certain configurations via the CSS of the document that is converted. This is
done using the proprietary at-rule @-ro-preferences
.
Example:
@-ro-preferences { /* The first page of the document should not be a cover page */ first-page-side: verso; }
Property Name | Values | Description |
first-page-side |
|
Sets on which side the first page of the document should be. By default it is
right , unless the document
direction is right-to-left.
|
first-page-side-view |
|
Sets on which side the first page of the document should appear in viewers, without impact
on styles or layout. By default it is the
same side as set by first-page-side .
|
page-layout |
|
Sets the initial view mode for the document. Whether two pages should be next to each other and how scrolling between the pages should work. |
initial-zoom |
|
Sets the initial zoom factor when opening the document. Can either be a specific percentage value or the zoom factor can be computed dynamically so that the page (or its content) fits into the window of the viewer application. Please note, that not all fit-values are supported by all viewers. Generally, fit-page support is more common. |
initial-page |
|
Sets number of the page that should be scrolled to when opening the document.
The default value is 1 . Values smaller than 1 are invalid.
|
pages-counter-offset |
|
Sets an optional offset to be added to the value of the pages counter.
Negative values are valid. The default value is 0 .
|
pdf-shape-optimization |
|
Sets whether shapes should be written into the PDF in a way that prevents visualization issues in certain PDF viewers. |
In most cases, PDFreactor is able to handle even very large documents, provided that enough memory is made available. However, if there is not enough memory available or if large tables cause conversions to be too slow, PDFreactor offers specialized functionalities that disable certain resource intensive features to allow processing such documents much more efficiently in regards to memory and time. Those can be used separately or in combination.
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));
--segmentation-enabled
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
.
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 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.
An OutputStream
should be
passed to the convert
method, so the document is streamed
directly to disk or socket instead of keeping it in memory.
Many PDF viewers and processors will not properly handle PDF files that are larger than 2GB.
When using PDFs in a review process it is helpful to be able to effectively annotate the document. While
HTML already provides elements
like ins
and del
, PDFreactor also offers more specialized features.
It is possible to add PDF comments to the document using the addComments
configuration
property like this:
config.setAddComments(true);
--add-comments
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; }
The visualization is ultimately dependent on the PDF viewer and may vary across viewers and/or platforms.
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.
In some cases, comments have a separate start and end tag. In this case the additional style rules -ro-comment-start or -ro-comment-end have to be set to match the comment's start and end elements.
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); }
To actually create a comment, you need to specify at least one of the following CSS properties: , , -ro-comment-start, or -ro-comment-end.
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.
Accessibility describes the possibility of making the content of a document available to the reader in a non-traditional or augmented way. When properly implemented, this grants readers with certain disabilities such as visual impairments or reading disorders access to all the information in the document.
There may also be various legal requirements in your country, such as Section 508 of the Rehabilitation Act in the United States, which demand accessible PDFs. Since this topic is highly complex and depends on your and your customers' countries, we will not go into further detail and this chapter is without any claim to completeness.
Accessible PDF documents require tagging. Tagged PDF files contain information about the structure, semantics and reading flow of the document. This information is stored in a tree structure of so-called "PDF tags"https://helpx.adobe.com/acrobat/using/editing-document-structure-content-tags.html#standard_pdf_tags.
For accessible documents it is recommended to use PDF/UAPDF/Universal Accessibility conformance. PDF/UA is the informal name for ISO 14289, the international standard for accessible PDF technology. Enabling PDF/UA conformance in PDFreactor automatically enables tagging and adds the required metadata to the PDF so that viewers or readers recognize the document as an accessible PDF/UA document. It can optionally be combined with PDF/A conformance, in which case we recommend PDF/A-3a over PDF/A-1a, as the latter imposes some limitations on the fidelity of tagging.
PDFreactor automatically determines the PDF tags not only from the HTML elements and CSS styles of the input document, but also from the resulting layout. This means that PDFreactor can even correctly tag complex structures automatically, including the following example cases. Block elements that directly contain text are always tagged as paragraphs so that the tag tree of the PDF remains valid. Tables spanning multiple pages with repeating headers and footers don't have those repeated in the tagging structure. Special document areas such as the footnote area are tagged as an "artifact", meaning the area is ignored by screen readers. The footnotes themselves are tagged in such a way that they are read as natural part of the normal text flow, so that the reading experience is not interrupted.
WAI-ARIAWeb Accessibility Initiative – Accessible Rich Internet Applications attributes in the input document are taken into account and can be used to manually override automatically determined tag types. There are also custom CSS properties that allow overriding the automatic determination or configuring it for best results.
The quality of automatic tagging depends highly on the quality of the input documents. Authors must ensure the content is properly structured and contains all required metadata. The following are the most important points to consider:
Use only valid and well-structured HTML
For headings use either h1
to h6
elements or nested
section
elements in combination with only h1
Provide alternative text for images, e.g. via the
alt
attribute of the img
element
Use caption and header elements for tables
Irrelevant elements, such as ones used exclusively as decorations, must be tagged as artifacts, so they are ignored (See ARIA and CSS examples)
Use WAI-ARIA attributes or styles to further customize accessibility information if necessary
For example, the following HTML markup is syntactically valid, but produces non-optimal accessibility data:
<h1>Document Title</h1> <h1>Heading</h1> <img src="image.png"> <table> <tr> <td>Col 1</td> <td>Col 2</td> </tr> <tr> <td>A</td> <td>B</td> </tr> </table>
Better markup would be the following, which includes additional information such as alternative text for images as well as table captions and column headers:
<h1>Document Title</h1> <section> <h1>Heading</h1> <img src="image.png" alt="My Image"> <table> <caption>My Table</caption> <thead> <tr> <th>Col 1</th> <th>Col 2</th> </tr> </thead> <tbody> <tr> <td>A</td> <td>B</td> </tr> </tbody> </table> </section>
Even without any further information or configuration, PDFreactor will automatically create an appropriate tag tree for the document snippet above. The result can be seen in the following screenshot:
WAI-ARIA is a technical specification published by the W3CWorld Wide Web Consortium. It specifies how to enhance the accessibility of web content and web applications. PDFreactor supports a subset of version 1.2 of this specification to enhance the accessibility of HTML documents intended for paginated output. It allows overriding the automatically determined tag types.
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:
WAI-ARIA attributes can be used to convey specific states to assistive technology. While most of the states are intended for interactive websites, PDFreactor supports a small subset that can be translated into accessibility information of static PDFs. Supported states and properties are:
aria-checked
aria-hidden
aria-describedby
aria-label
aria-labelledby
aria-level
aria-selected
aria-valuenow
aria-valuetext
The ARIA specification uses certain attributes (such as aria-describedby
) and HTML
elements (such as label
) to determine an accessible name and description for document
components. PDFreactor supports this approach and automatically maps this accessibility information
to appropriate PDF data structures, the PDF tags.
Please refer to the well-documented WAI-ARIA specificationhttps://www.w3.org/TR/wai-aria-1.2/ on how to properly use ARIA roles, states and properties to provide accessibility information.
If your document uses custom elements for headings, you can tag those as proper headings like this:
<div aria-role="heading" aria-level="1">My heading</div>
Using ARIA attributes to specify headings also sets the matching PDF bookmark level.
Content such as components that don't work in PDFs and should be ignored by screen readers can be tagged as artifact, eliminating the element and its subtree from being tagged, like this:
<div aria-role="dialog">A dialog that cannot be displayed in PDF</div>
Similarly elements, and their subtree, can be removed without changing their role, using the attribute aria-hidden
:
<div aria-hidden="true"> <p>Decorative or otherwise irrelevant content</p> </div>
Artifacts are excluded from tagging, including their entire subtree. You can also exclude a single container element while keeping its content:
<div aria-role="presentation"> <!-- Irrelevant container --> <p>Relevant text</p> </div>
A structure that is semantically a table, but does not consist of table
elements or elements with table display styles, and so is not laid out as a
table, just needs table roles for PDFreactor to tag it as a table structure.
In cases like the following, the first row group is also automatically tagged
as thead
, when it has more header cells than other cells.
<div role="table"> <div role="rowgroup"> <div role="row"> <span role="columnheader">Cell H / 1</span> <span role="columnheader">Cell H / 2</span> </div> </div> <div role="rowgroup"> <div role="row"> <span role="cell">Cell 1 / 1</span> <span role="cell">Cell 1 / 2</span> </div> <div role="row"> <span role="cell">Cell 2 / 1</span> <span role="cell">Cell 2 / 2</span> </div> <div role="row"> <span role="cell">Cell 3 / 1</span> <span role="cell">Cell 3 / 2</span> </div> <div role="row"> <span role="cell">Cell 4 / 1</span> <span role="cell">Cell 4 / 2</span> </div> </div> </div>
When using conflicting ARIA attributes and CSS for tagging, the CSS properties take precedence.
Setting -ro-pdf-tag-type
to auto
disables the processing of role
attributes for the affected elements, as that processing is implemented via a user agent style sheet.
When the automatic determination of PDF tags must be overridden and WAI-ARIA attributes are insufficient or inconvenient, proprietary CSS properties can be used, either in the document or in a user style sheet.
The proprietary CSS property can be used in various ways to ensure the correct tag types for elements and structures.
The initial value is auto
, which means that PDFreactor will automatically determine the tag type.
In most cases this results in correct tagging without the need for manual intervention.
However, there are cases where the structure of the HTML and the resulting layout do not match the intended semantic structure.
For example a table could be created from styled div
and span
elements.
Conversely an HTML table
could be used just for layout.
If your document uses custom elements for headings, you can tag those as proper headings like this:
div.heading1 { -ro-pdf-tag-type: h1; }
For headings set via CSS it is highly recommended to also set the matching bookmark level.
Content such as components that don't work in PDFs and should be ignored by screen readers can be tagged as artifact like this:
div.decoration { -ro-pdf-tag-type: artifact; }
Artifacts are excluded form tagging, including their entire subtree. You can also exclude a single container element while keeping its content:
div.irrelevantContainer { -ro-pdf-tag-type: none; }
It is also possible to ensure the tag type is determined from layout information, ignoring role
attributes:
ol, ul, li { -ro-pdf-tag-type: auto; }
The following series of example shows how to correctly and safely tag an ol
element with the class "nonlist",
that is intended to be considered just a sequence of paragraphs instead of a list.
It starts with the most simple approach, which is also compatible with older versions of PDFreactor,
and then introduces more advanced concepts, which are highly recommended for best results:
With regards to accessibility the ol
and li
elements should be treated
like the div
and p
elements, respectively.
<div> <p>A paragraph</p> <p>A paragraph</p> </div> <ol class="nonlist"> <li>A list item, to be considered a paragraph</li> <li>A list item, to be considered a paragraph</li> </ol> <div> <p>A paragraph</p> <p>A paragraph</p> </div>
The most simple style to turn that list into a sequence of paragraphs is to use with a .
ol.nonlist { -ro-pdf-tag-type: div; } ol.nonlist > li { -ro-pdf-tag-type: p; }
The previous sample assumes that every li
element in such a list only contains inline content, like text.
However, the following is also valid HTML:
<div> <p>A paragraph</p> <p>A paragraph</p> </div> <ol class="nonlist"> <li>A list item, to be considered a paragraph</li> <li><p>A paragraph inside a list item, to be considered a paragraph inside a block</p></li> </ol> <div> <p>A paragraph</p> <p>A paragraph</p> </div>
The first li
requires the type p
, while the second one requires div
.
To automatically use the right type for a specific scenario you can specify a instead of a specific type.
(See the table below for a list of kinds and their matching types.)
ol.nonlist { -ro-pdf-tag-type: simple-block-strict; } ol.nonlist > li { -ro-pdf-tag-type: simple-block; }
While the second example will ensure a valid and useful PDF tag tree for most common scenarios, some complex documents require one further step. Consider the following, comparatively artificial, sample HTML:
<div style="display: table"> <ol class="nonlist" style="display: table-row-group"> <li style="display: table-row"> <p style="display: table-cell">Content</p> </li> </ol> </div>
The sample creates a table by using explicit 'display' styles.
When no tagging styles are applied the automatic tag type determination
will correctly tag the ol
and li
elements as TBody
and TR
,
respectively, based on them being laid out as parts of a table.
Using the styles from one of the previous examples would change the tags of those elements, breaking the table structure in the tag tree.
To automatically avoid this, but still affect HTML structures like in the previous examples, you can add conditions,
that ensure types or kinds are only overridden when the automatic tag type determination had a specific result,
which can be specified as a type or kind, in this case list-struct
.
Each condition is specified as part of a pair, first the condition then the type or kind to use when it is met.
Multiple such pairs can be specified, separated by commas. Those are tried in order and the first match is applied.
For the case when no condition applies, a single type or kind can be specified after a final comma.
When this is omitted the default behavior is auto
.
"type or kind" also includes auto
, none
and artifact
.
ol.nonlist { -ro-pdf-tag-type: list-struct simple-block-strict; } ol.nonlist > li { -ro-pdf-tag-type: list-struct simple-block; }
Kind | Div | P | Span | NonStruct, artifact, none |
L, LI, Lbl, LBody |
Table, TBody, THead, TFoot, TR, TD, TH, Caption |
simple | ||||||
simple-block | ||||||
simple-block-strict | ||||||
simple-inline | ||||||
list-struct | ||||||
table-struct |
In addition to the tag type, PDFreactor also automatically determines some attributes for each tag. As with the type, it may be necessary to override or specify those manually. For that you can use the following CSS properties:
The default value for the -ro-pdf-tag-*
CSS properties is auto
, which will
automatically populate the matching PDF attributes (or leave them blank if appropriate).
Properties specifying text attribute, like alternative text, optionally take a comma-separated list of items.
The first item whose resolved value is non-empty will be used for the resulting value.
Each item can consist of multiple space-separated values which are then concatenated.
You also have direct access to the ARIA specification's accessible name and description
via the CSS values aria-name
and aria-description
, respectively.
The following style declaration is used to customize the alt text of image elements.
img { -ro-pdf-tag-alt: attr("data-alt-text"), auto, "Image " counter(images); }
To determine the resulting value, PDFreactor iterates the list items from left to right, using the first item with a non-empty value:
The first item in the value list takes the text directly from a custom
data-alt-text
HTML attribute. If the attribute's value is
empty or the attribute is not present, the next item is evaluated.
The second item's value is auto
, which means PDFreactor tries to find an
alternative text automatically, depending on the element, its styles, attributes and context.
If no alternative text can be determined, the next item is evaluated.
The third item consists of a concatenation of the string "Image " and the value of the custom counter "images". Assuming that this is the seventh image, this would result in the string "Image 7". Note that such a string this is not considered best practice since it does not convey any meaningful information. It is presented here merely as a technical example.
In certain cases it might be useful to use both the ARIA name and description for tagging data.
.myAccessibleElements { -ro-pdf-tag-alt: aria-name ": " area-description; }
In this example, a concatenation of the ARIA name and description is used for the alternative text. Since PDF tags don't have attributes for both values, such an approach may only be appropriate for certain use cases.
When using conflicting ARIA attributes and CSS for tagging, the CSS properties take precedence.
Setting -ro-pdf-tag-type
to auto
disables the processing of role
attributes for the affected elements, as that processing is implemented via a user agent style sheet.
When using XML documents as input, instead of HTML, PDFreactor will still automatically determine tag types and attributes based on the layout. However, further CSS is necessary to cover semantic information.
Most importantly correct tag types have to be ensured.
In DocBook XML, for example, you can map the "title" elements inside "sect1" elements to the PDF
tag type H2
(heading, level 2):
sect1 > title { -ro-pdf-tag-type: simple-block h2; }
There are also relevant tag attributes, especially the alternative text for images. You can use the "desc" attributes of "image" elements for that, like this:
image { -ro-pdf-tag-type: figure; } image[desc] { -ro-alt-text: attr(desc); }
For form elements, you can use the CSS 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. When converting HTML, the names are adopted
from the value
attribute of the form element.
Using the property, 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.
The User Agent is an optional object that is created independently from PDFreactor and can be passed to multiple PDFreactor conversions. When a User Agent object is used, all PDFreactor conversions that are configured with this object will share a single HTTP client implementation. This means that these conversions share a common cookie store and (if enabled) a HTTP resource cache.
Do not use a common User Agent for conversions from different parties! This is considered insecure as conversions may find out information about other conversions by e.g. sniffing the cookie store or the HTTP cache.
The User Agent uses security settings similar to the Configuration object since it is a security critical component. When using a User Agent, its security settings override any security settings of the Configuration, even if these are more specific. So it is recommended to not specify any security settings at all on the Configuration object when using a User Agent.
Similar to security settings, the User Agent also uses network settings to specify connection behavior. These also override any network settings of the Configuration.
Browser-like HTTP caching can be enabled when using a User Agent. This is useful if you convert many documents that use a lot of identical cacheable resources like images. The cache is file system based and persists beyond the lifetime of a single conversion. There are various configuration options to ensure that the cache does not exceed certain limits, as you only have indirect control over its contents.
The HTTP Cache can be configured in several ways:
path
— The file system path to a directory where the cached resources will be
stored. Please note that the contents of this directory must not be manipulated directly as this
can lead to unexpected behavior during conversions.
maxEntries
— The maximum number of entries that are allowed in this cache. If the
number is exceeded, old entries will be discarded. The default value is 100.
maxObjectSize
— The maximum number of bytes a resource may have to be cached.
Larger resources won't be cached. The default value is 5,000,000 bytes, i.e. 5MB.
The maximum size of the HTTP Cache can be determined by multiplying maxEntries
by
maxObjectSize
. So by default, the HTTP cache would not exceed 500MB.
To be able to display text PDFreactor requires font data. This font data must be in TTF True Type Font or in OTF Open Type Font format and may come from different types of sources (see Font Sources).
Using OpenType fonts with CFF outlines requires Java SE 9 or higher.
The font data of PDFreactor may come from different types of sources.
PDFreactor contains fonts that will be used for the Default Font Mapping when no other fonts could be registered on the system, e.g. because of insufficient file permissions or due to the fact that there are no fonts available.
These fonts are distributed by RealObjects and licensed by their respective authors under the SIL Open Font License A free and open source license designed for fonts (https://openfontlicense.org/documents/OFL.txt) , the Apache License A permissive free software license written by the Apache Software Foundation (https://www.apache.org/licenses/LICENSE-2.0) or are in the Public Domain.
Original Font Name | Type | PDFreactor Font Name | License |
Arimo |
sans-serif | RealObjects core sans-serif |
Apache License, Version 2.0 |
Tinos |
serif | RealObjects core serif |
Apache License, Version 2.0 |
Cousine |
monospace | RealObjects core monospace |
Apache License, Version 2.0 |
Dancing Script |
cursive | RealObjects core cursive |
SIL Open Font License, Version 1.1 |
Orbitron |
fantasy | RealObjects core fantasy |
SIL Open Font License, Version 1.1 |
Quivira |
symbol | RealObjects core symbol |
Public Domain (http://en.quivira-font.com/notes.php) |
Additionally the core fonts contain fallback fonts for symbols and characters from non-Latin
languages.
Those are the Noto
fonts (SIL Open Font License 1.1), Nanum Gothic
(SIL
Open Font License 1.1), and Droid Sans
Fallback
(Apache License 2.0).
The main sources PDFreactor uses to retrieve font data are:
fonts registered with the Java VM
fonts located in system font folders
Both provide fonts physically available to PDFreactor.
PDFreactor registers fonts from these sources automatically. Java VM fonts are usually located in JAVA_HOME/jre/lib/fonts. The location of system font folders is platform dependent:
Windows
System Root (usually C:\Windows)\fonts
User Home\AppData\Local\Microsoft\Windows\fonts
macOS
/Library/fonts
/System/Library/fonts
User Home/Library/fonts
/Network/Library/fonts/
Linux/Unix
/usr/share/fonts
/usr/local/share/fonts
User Home/.fonts
User Home/.local/share/fonts
On Linux, not all required system libraries may be installed on the system by default.
To use system fonts on Linux, the fontconfig
system library and some basic fonts such
as dejavu fonts
must be installed.
For Image Output PDFreactor also requires X11FontManager
,
libpng
, and libfreetype
.
These libraries and basic fonts are dependencies of the Fontconfig package, which is available for
common Linux distributions.
PDFreactor can be configured to ignore all system fonts and only use fonts that either have been specifically added via configuration properties or that are web fonts from style sheets. This is useful if the system either has no fonts or if you want to avoid system-dependent output. See for examples.
If PDFreactor was unable to retrieve any font data, fonts from the Core Fonts Pack will be used. (see ).
PDFreactor allows setting additional fonts that are neither located in the system font directory nor the font directory of the Java VM. These fonts still need to be physically available to PDFreactor.
To register these fonts with PDFreactor via the API, use the following configuration properties:
fontDirectories
— The fonts in the specified directories and all their
subdirectories will be used by PDFreactor.
fonts
— Additional fonts from a specified source URL.
For each directory added by the fontDirectories
property and for each of their
subdirectories, a separate font cache is created. Should the
contents of these directories change, please delete the font cache files before running PDFreactor.
See the Chapter The Font Cache Mechanism for more information
about the font cache.
Font directories can be added like this:
config.setFontDirectories("/myFonts1", "/myFonts2/corporate");
--font-directories "/myFonts1" "/myFonts2/corporate"
Instead of adding entire font directories that PDFreactor will scan, you can also add specific fonts like this:
config.setFonts( new Font().setFamily("My Font") .setBold(true) .setItalic(true) .setSource("https://url/to/font.ttf"));
-C config.json
With the following config.json:
{ "fonts": [ { "family": "My Font", "bold": true, "italic": true, "source": "https://url/to/font.ttf" } ]}
PDFreactor is capable of using fonts defined in CSS via the @font-face
rule. These
fonts are
retrieved by PDFreactor along with other resources of the document (e.g. images) and will only be
used to render the document
they belong to.
@font-face { font-family: "My Font"; src: url("https://www.my-server.com/fonts/my-font.ttf"); }
PDFreactor uses a font cache to store required information about available fonts.
One of the steps PDFreactor performs on startup is registering fonts. The first time this is done will take some time since every font inside the font directories available to PDFreactor will be identified and registered.
At the end of this step PDFreactor creates a font cache that will be used on subsequent conversions to increase performance. The font cache persists until the Java VM running PDFreactor is terminated.
If so configured (see ), PDFreactor can write its font cache onto the file system so that it persists between Java VM restarts. This significantly reduces startup time as it ensures the rendering process will start as soon as possible.
If font cache files are present, new fonts put into the font directories available to PDFreactor will be ignored by PDFreactor unless the font cache files have been deleted. Then PDFreactor will create new font cache files on the next startup as it would on its first one.
To delete the font cache files, visit the user.home/.PDFreactor directory (or a custom directory if you configured one) and delete all files inside it.
It is possible to customize the registration and caching of fonts via the API.
The following configuration properties are used to control the font handling behavior of PDFreactor:
cacheFonts
— Activates or deactivates the file system font cache.
fontCachePath
—
Specifies the location where the font cache files should be
stored.
disableSystemFonts
— If set to true, PDFreactor will neither register system
fonts, nor
use the font cache file for them if it exists.
disableFontRegistration
— Specifies that parts of the font caching mechanism
should be disabled. This is a legacy property. In nearly all cases you should use either
cacheFonts
or disableSystemFonts
.
To optimize startup time in scenarios where the PDFreactor library's Java VM is frequently restarted, it is recommended to enable a font cache. The PDFreactor Web Service automatically caches fonts.
config.setCacheFonts(true);
--cache-fonts
As mentioned before, the default font cache files are located in the
user.home/.PDFreactor directory. To customize this location,
you can use the configuration property fontCachePath
.
config.setFontCachePath("/myPDFreactor/fontcache");
--font-cache-path "/myPDFreactor/fontcache/cache.dat"
PDFreactor can be configured to ignore all system fonts and only use fonts that either have been specifically added via configuration properties or that are web fonts from style sheets:
config.setDisableSystemFonts(true);
--disable-system-fonts
Browsers usually match the generic font families with fonts installed on the host system, but PDFreactor consciously matches them with its own specific core fonts. This is done so that documents which use generic font families look consistent across all systems, no matter which fonts (if any) are installed.
Should it be required to match generic font families with other fonts, it is recommended to use to e.g. map the family name "serif" to the desired font.
The generic font families are mapped as follows:
Generic Font Family | Matched Core Font | System Font Example |
sans-serif | Arimo | Arial |
serif | Tinos | Times New Roman |
monospace | Cousine | Courier New |
cursive | Dancing Script | Comic Sans MS |
fantasy | Orbitron | Impact |
It is possible to add a font alias name for a font available in the system font directory or the font directory of the Java VM. The font alias name allows referencing to a font using a different name.
Authors can thus use a font alias name as the font-family value in CSS instead of the actual font name. Exchanging the font in all these documents can be done by changing the actual font behind the alias.
To define a font alias name via the Java API use the following configuration property:
fontAliases
— Alias families for registered fonts.
The following example maps the registered font Arial to the name "My Font". So each time you refer to the name "My Font" in CSS, Arial is used internally.
config.setFontAliases( new Font().setFamily("My Font") .setSource("Arial"));
-C config.json
With the following config.json:
{ "fontAliases": [ { "family": "My Font", "source": "Arial" } ]}
Whenever the current font cannot be used to display a certain character, an automatic font fallback is used to find a replacement font for this character. To do so fonts are iterated according to the following parameters:
The font-family property of the current element
The configuration property fontFallback
An internal list of recommended fonts
All fonts on the system, starting with those with the most glyphs
A list of fallback fonts can be specified like this:
config.setFontFallback("My Font", "Arial");
--font-fallback "My Font" "Arial"
ro
or window.ro
object provides access to
PDFreactor's proprietary
JavaScript API.
The exception message.
ro.layout
.
The page index.
The DOM element.
The DOM element.
A string specifying which content to return:
"before"
: Retrieves the "before"
generated
content of the element.
"after"
: Retrieves the "after"
generated
content of the element.
"text"
: Retrieves the content of the element, excluding its
generated content.
"all"
: Retrieves the content of the element.
If omitted "all"
will be applied as default.
Both "text"
and "all"
includes the generated content
of all descendants.
Returns the current total number of pages of the document.
ro.pdf
.
Enables or disables attachments specified in style sheets.
Enables or disables comments in the PDF document.
Enables or disables overprinting.
Enables or disables embedding of image previews per page in the PDF document.
Enables or disables tagging of the PDF document.
Enables or disables the 'annotations' restriction in the PDF document.
Enables or disables the 'assembly' restriction in the PDF document.
Enables or disables the 'copy' restriction in the PDF document.
Enables or disables the 'degraded printing' restriction in the PDF document.
Enables or disables the 'fill in' restriction in the PDF document.
Enables or disables the 'modify contents' restriction in the PDF document.
Enables or disables the 'printing' restriction in the PDF document.
Enables or disables the 'screen readers' restriction in the PDF document.
Adds a file attachment to PDF document. All attachments that have been set previously in the PDFreactor integration are included as attachments with binary content which will be base64-encoded.
Sets the value of the author field of the PDF document.
Convenience method to set pages-per-sheet properties and page order in one step to create a booklet.
Sets the value of creator field of the PDF document.
Adds custom properties to the PDF document. An existing property of the same name will be replaced.
Disables bookmarks in the PDF document.
Disables links in the PDF document.
A type containing settings related to PDF encryption.
Sets the value of the keywords field of the PDF document.
Sets the owner password of the PDF document.
Sets the page order of the direct result of the conversion.
If the merge mode is set to ARRANGE
(see ), this
property is also used to specify the position of inserted pages from an existing PDF.
A description of the syntax can be found in the section.
Additionally, the pageOrder
constants can be used:
"BOOKLET"
: Page order mode to arrange all pages in booklet order.
"BOOKLET_RTL"
: Page order mode to arrange all pages in
right-to-left booklet order.
"EVEN"
: Page order mode to keep even pages only.
"ODD"
: Page order mode to keep odd pages only.
"REVERSE"
: Page order mode to reverse the page order.
Sets the properties of a sheet on which multiple pages are being arranged.
If cols or rows is less than 1, no pages-per-sheet processing is done. This is the case by default.
Sets a pair of trigger event and PDF script. The script is triggered on the specified event.
A PDF script is JavaScript that is executed by a PDF viewer (e.g. Adobe Reader). Note that most viewers do not support this feature.
Enables or disables a print dialog to be shown upon opening the generated PDF document by a PDF viewer.
Sets the value of the subject field of the PDF document.
Sets the value of the title field of the PDF document.
Sets the user password of the PDF document.
The index of the page of this box. The first page has the index 0.
Whether the page of this box is on the left.
The PageDescription of the page of this box. It contains the data of the page from the moment when this BoxDescription was created.
Returns an array of LineDescriptions for this box if the box contains text directly.
Returns an object providing access to BoxDescription arrays
for the generated content via type name strings.
Available generated content type names are "before"
and
"after"
(for normal HTML elements) and "content"
(for page
margin boxes).
Please note that generated content of inline elements is not yet accessible in this way.
For boxes inside a multi-column layout this returns the index of the column the box is in. Otherwise it returns -1. The index starts at 0 for the first column of the multi-column container element. It increases by one for each further column or column-span and is not reset on new pages or by column spans.
For boxes inside a multi-column layout this returns the local index of the column the box is in. Otherwise it returns -1. The local index starts at 0 for the first column of the multi-column container element. It increases by one for each further column and is reset to 0 on new pages as well as on and after column spans.
For boxes inside a Region this returns the index of that region. Otherwise it returns -1. The index starts at 0 for the first region in its chain. It increases by one for each further region in the same chain and is not reset on new pages.
For boxes inside a Region this returns the local index of that region. Otherwise it returns -1. The local index starts at 0 for the first region in its chain. It increases by one for each further region in the same chain and is reset to 0 on new pages.
The desired length unit in which the dimensions and coordinates will be returned.
(defaults to "px"
)
The desired length unit in which the dimensions and coordinates will be returned.
(defaults to "px"
)
The desired length unit in which the dimensions and coordinates will be returned.
(defaults to "px"
)
The desired length unit in which the dimensions and coordinates will be returned.
(defaults to "px"
)
The desired length unit in which the dimensions and coordinates will be returned.
(defaults to "px"
)
The desired length unit in which the dimensions and coordinates will be returned.
(defaults to "px"
)
The desired length unit in which the dimensions and coordinates will be returned.
(defaults to "px"
)
The desired length unit in which the dimensions and coordinates will be returned.
(defaults to "px"
)
The desired length unit in which the dimensions and coordinates will be returned.
(defaults to "px"
)
The index of this page. The first page has the index 0.
Whether this page is on the left.
The name of this page, if it is a named page and an empty string otherwise.
An array containing all names of this page or an empty array if there are none.
The DOM Range of the content of this page. The start- and
endContainer are the most deeply nested nodes at the respective
page breaks. Returns null
if the page is empty.
The DOM Range of the content of this page. The start- and
endContainer are the least deeply nested nodes at the respective
page breaks. Returns null
if the page is empty.
Returns an object providing access to BoxDescriptions for the
page margin boxes via margin box name strings like "top-left"
.
The BoxDescriptions for the content of a margin box are available via the
'content
' key of its generatedContentDescriptions
object.
The desired length unit in which the dimensions and coordinates will be returned.
(defaults to "px"
)
The desired length unit in which the dimensions and coordinates will be returned.
(defaults to "px"
)
getMarginRect
and matches the page size.The desired length unit in which the dimensions and coordinates will be returned.
(defaults to "px"
)
getTrimRect
and matches the page size.The desired length unit in which the dimensions and coordinates will be returned.
(defaults to "px"
)
The desired length unit in which the dimensions and coordinates will be returned.
(defaults to "px"
)
The desired length unit in which the dimensions and coordinates will be returned.
(defaults to "px"
)
The desired length unit in which the dimensions and coordinates will be returned.
(defaults to "px"
)
null
if none is set.
The desired length unit in which the dimensions and coordinates will be returned.
(defaults to "px"
)
null
if none is set.
The desired length unit in which the dimensions and coordinates will be returned.
(defaults to "px"
)
The DOM Range from the beginning to the end of the text of the
line or null
for empty lines.
The desired length unit in which the dimensions and coordinates will be returned.
(defaults to "px"
)
The desired length unit in which the dimensions and coordinates will be returned.
(defaults to "px"
)
The content of the attachment. If it is a string the binary property specifies whether to treat it as UTF-8 or Base64. May be omitted.
If data is not specified, the attachment will be retrieved from this URL. If this is "#" the input document URL is used instead.
The file name associated with the attachment. It is recommended to specify the correct file extension. If this is omitted the name is derived from the URL.
The description of the attachment. If this is omitted the name is used.
This property indicates whether the data property, when it contains a string, is decoded
as Base64 binary data or UTF-8 text.
If omitted it is treated as false
, meaning that string content is
considered UTF-8 text.
The size of the sheet as CSS value, e.g. "A3", "letter landscape", "15in 20in", "20cm 30cm".
The sheet size as CSS size, e.g. "A4", "letter landscape", "15in 20in", "20cm 30cm".
Whether or not the reading order of the booklet should be right-to-left.
The encryption type to be used. The default is "NONE"
. Value is one of
the following constants:
"NONE"
: Indicates that the document will not be encrypted. If encryption is
disabled, then no user password or owner password can be used.
"RC_40"
: Indicates that the document will be encrypted using RC4 40 bit encryption.
"RC_128"
: Indicates that the document will be encrypted using RC4 128 bit encryption.
"AES_128"
: Indicates that the document will be encrypted using AES 128 bit encryption.
"AES_256"
: Indicates that the document will be encrypted using AES 256 bit encryption.
Sets the owner password of the PDF document.
Sets the user password of the PDF document.
Enables or disables the 'annotations' restriction in the PDF document.
The default value is false
.
Enables or disables the 'assembly' restriction in the PDF document.
The default value is false
.
Enables or disables the 'copy' restriction in the PDF document.
The default value is false
.
Enables or disables the 'degraded printing' restriction in the PDF document.
The default value is false
.
Enables or disables the 'fill in' restriction in the PDF document.
The default value is false
.
Enables or disables the 'modify contents' restriction in the PDF document.
The default value is false
.
Enables or disables the 'printing' restriction in the PDF document.
The default value is false
.
Enables or disables the 'screen readers' restriction in the PDF document.
The default value is false
.
The key.
The value.
The number of columns per sheet.
The number of rows per sheet.
The sheet size as CSS size, e.g. "A4", "letter landscape", "15in 20in", "20cm 30cm".
The sheet margin as CSS margin, e.g. "1in", "1cm 1.5cm", "10mm 20mm 10mm 30mm".
null
is interpreted as 0mm.
The horizontal and vertical space between pages on a sheet as CSS value,
for example "0.1in" or "5mm 2mm". null is interpreted as "0mm"
.
The direction in which the pages are ordered on a sheet. Value is one of the following constants:
"DOWN_LEFT"
: Arranges the pages on a sheet from top to bottom and
right to left.
"DOWN_RIGHT"
: Arranges the pages on a sheet from top to bottom and
left to right.
"LEFT_DOWN"
: Arranges the pages on a sheet from right to left and
top to bottom.
"LEFT_UP"
: Arranges the pages on a sheet from right to left and
bottom to top.
"RIGHT_DOWN"
: Arranges the pages on a sheet from left to right and
top to bottom.
"RIGHT_UP"
: Arranges the pages on a sheet from left to right and
bottom to top.
"UP_LEFT"
: Arranges the pages on a sheet from bottom to top and
right to left.
"UP_RIGHT"
: Arranges the pages on a sheet from bottom to top and
left to right.
The event on which the script is executed. Value is one of the following constants:
"AFTER_PRINT"
: This event is triggered after the PDF has been
printed by the viewer application.
"AFTER_SAVE"
: This event is triggered after the PDF has been saved
by the viewer application.
"BEFORE_PRINT"
: This event is triggered before the PDF is printed
by the viewer application.
"BEFORE_SAVE"
: This event is triggered before the PDF is saved by
the viewer application.
"CLOSE"
: This event is triggered when the PDF is closed by the
viewer application.
"OPEN"
: This event is triggered when the PDF is opened in the
viewer application.
The script source that should be executed.
PDFreactor supports the following barcode symbologies, each handling some of the
-ro-barcode-*
CSS properties differently.
These -ro-barcode-*
properties apply to all barcode types:
These apply to all barcode types with human readable text:
-ro-barcode-encoding
applies to all
barcode types, however they don't necessarily support all 3 available data types.
-ro-barcode-size
applies to most barcode
types. If the property is not explicitly mentioned, it adjusts the bar height.
Please refer to the CSS documentation for more information.
Some barcode symbologies impose additional restrictions on the input data besides limiting the allowed characters.
If the -ro-barcode-type
property is
mentioned below, the entry always refers to its optional last argument.
.barcode { -ro-replacedelement: barcode; -ro-barcode-type: code2of5 interleaved enabled; -ro-barcode-content: "1234567890"; }
The element's default styles are described in the user agent style sheet. While most of these styles are adapted from the specificationssee https://html.spec.whatwg.org/multipage/rendering.html and match the styles of browsers, PDFreactor adds some sets of style rules, for example those related to pagination:
Selector | Declarations |
@page |
size: A4; margin: 2cm; white-space: pre-line; counter-increment: page;
|
h1, h2, h3, h4, h5, h6 | break-after: avoid; |
@footnote |
padding-top: 6pt; border-top: solid black thin; -ro-border-length: 30%; margin-top: 6pt;
|
::footnote-call |
counter-increment: footnote 1; content: counter(footnote); line-height: 100%; font-size: 65%; vertical-align: super;
|
::footnote-marker |
content: counter(footnote) ". "; |
PDFreactor supports the following CSS selectors which select elements that have certain attributes:
Attribute selector | Meaning | CSS Level |
Elem[attr] | An Elem element with a attr attribute.
|
CSS 2.1 |
Elem[attr="val"] | An Elem element whose attr attribute value is exactly equal to
"val" .
|
CSS 2.1 |
Elem[attr~="val"] | An Elem element whose attr attribute value is a list of
whitespace-separated values, one of which is exactly equal to "val" .
|
CSS 2.1 |
Elem[attr^="val"] | An Elem element whose attr attribute value begins exactly with the
string "val" .
|
CSS 3 |
Elem[attr$="val"] | An Elem element whose attr attribute value ends exactly with the
string "val" .
|
CSS 3 |
Elem[attr*="val"] | An Elem element whose attr attribute value contains the substring
"val" .
|
CSS 3 |
A series | Size [mm] | RA oversizes | Size [mm] | SRA oversizes | Size [mm] |
A0 | 841 x 1189 | RA0 | 860 x 1220 | SRA0 | 900 x 1280 |
A1 | 594 x 841 | RA1 | 610 x 860 | SRA1 | 640 x 900 |
A2 | 420 x 594 | RA2 | 430 x 610 | SRA2 | 450 x 640 |
A3 | 297 x 420 | RA3 | 305 x 430 | SRA3 | 320 x 450 |
A4 | 210 x 297 | RA4 | 215 x 305 | SRA4 | 225 x 320 |
A5 | 148 x 210 | RA5 | 152 x 215 | SRA5 | 160 x 225 |
A6 | 105 x 148 | RA6 | 107 x 152 | SRA6 | 112 x 160 |
A7 | 74 x 105 | RA7 | 76 x 107 | SRA7 | 80 x 112 |
A8 | 52 x 74 | RA8 | 53 x 76 | SRA8 | 56 x 80 |
A9 | 37 x 52 | ||||
A10 | 26 x 37 |
B series | Size [mm] |
B1 | 707 x 1000 |
B2 | 500 x 707 |
B3 | 353 x 500 |
B4 | 250 x 353 |
B5 | 176 x 250 |
B6 | 125 x 176 |
B7 | 88 x 125 |
B8 | 62 x 88 |
B9 | 44 x 62 |
B10 | 31 x 44 |
C series | Size [mm] |
C1 | 648 x 917 |
C2 | 458 x 648 |
C3 | 324 x 458 |
C4 | 229 x 324 |
C5 | 162 x 229 |
C6 | 114 x 162 |
C7 | 81 x 114 |
C8 | 57 x 81 |
C9 | 40 x 57 |
C10 | 28 x 40 |
Page format | Size [in] |
Letter | 8.5 x 11 |
Legal | 8.5 x 14 |
Ledger | 11 x 17 |
Invoice | 5.5 x 8 |
Executive | 7.25 x 10.5 |
Broadsheet | 17 x 22 |
ISO 639-1 | Language |
af | Afrikaans |
as | Assamese |
bg | Bulgarian |
bn | Bengali, Bangla |
ca | Catalan |
cy | Welsh |
da | Danish |
de | New German |
de-1901 | German traditional |
de-CH | German, Switzerland |
el | Greek, Modern |
el_Polyton.hyp | Greek, Polyton |
en | English (US) |
en-GB | English (GB) |
eo | Esperanto |
es | Spanish |
et | Estonian |
eu | Basque |
fi | Finnish |
fr | French |
fur | Friulian |
ISO 639-1 | Language |
gl | Galician |
grc | Greek, Ancient |
gu | Gujarati |
hi | Hindi |
hr | Croatian |
hsb | Upper Sorbian |
ia | Interlingua |
id | Indonesian (Bahasa Indonesia) |
is | Icelandic |
it | Italian |
ka | Georgian |
kmr | Kurmanji (Northern Kurdish) |
kn | Kannada |
la | Latin |
la | Latin |
la-CL | Latin |
lt | Lithuanian |
ml | Malayalam |
mn | Mongolian |
mr | Marathi |
mul | Multiple languages |
ISO 639-1 | Language |
nb | Norwegian Bokmål |
nl | Dutch |
nn | Norwegian Nynorsk |
oc | Occitan |
or | Oriya |
pa | Panjabi |
pl | Polish |
pms | Piemontese |
pt | Portuguese |
rm | Romansh |
ro | Romanian |
ru | Russian |
sa | Sanskrit |
sl | Slovenian |
sr-Cyrl | Serbian, Cyrillic |
sr-Latn | Serbian, Latin |
sv | Swedish |
ta | Tamil |
te | Telugu |
th | Thai |
tk | Turkmen |
tr | Turkish |
uk | Ukrainian |
Unit | Description |
mm | millimeters |
cm | centimeters |
q | quarter-millimeters |
in | inches |
pt | points |
px | pixels |
pc | pica |
Unit | Description |
-ro-pw -ro-pi |
Equal to 1% of the width of the first page, including its margins. |
-ro-ph -ro-pb |
Equal to 1% of the height of the first page, including its margins. |
-ro-pmin | Equal to the smaller of '-ro-pw' and '-ro-ph'. |
-ro-pmax | Equal to the larger of '-ro-pw' and '-ro-ph'. |
-ro-bw -ro-bi |
Equal to 1% of the width of the page bleed box of the first page. |
-ro-bh -ro-bb |
Equal to 1% of the height of the page bleed box of the first page. |
-ro-bmin | Equal to the smaller of '-ro-bw' and '-ro-bh'. |
-ro-bmax | Equal to the larger of '-ro-bw' and '-ro-bh'. |
Unit | Description |
% | percent |
em | Relative to the font size of the element. |
rem | Relative to the font size of the root element. |
ex | Equal to the used x-height of the first available font. |
ch | Equal to the width of the "0" glyph in the font of the element. |
vw vi |
Equal to 1% of the width of the content area of the first page. |
vh vb |
Equal to 1% of the height of the content area of the first page. |
vmin | Equal to the smaller of 'vw' and 'vh'. |
vmax | Equal to the larger of 'vw' and 'vh'. |
cap | Equal the capital letter height of the font. |
ic | Equal to the width of the glyph "水" (U+6C34) in the font of the element. |
lh | Equal to the line height of the element. |
rlh | Equal to the line height of the root element. |
Units | Synonymous Units |
vw vi | lvw , lvi , svw ,
svi , dvw , dvi
|
vh vb | lvh , lvb , svh ,
svb , dvh , dvb
|
vmin | lvmin , svmin , dvmin |
vmax | lvmax , svmax , dvmax |
Color name | Color | hex RGB | Decimal |
aliceblue | #F0F8FF | 240,248,255 | |
antiquewhite | #FAEBD7 | 250,235,215 | |
aqua | #00FFFF | 0,255,255 | |
aquamarine | #7FFFD4 | 127,255,212 | |
azure | #F0FFFF | 240,255,255 | |
beige | #F5F5DC | 245,245,220 | |
bisque | #FFE4C4 | 255,228,196 | |
black | #000000 | 0,0,0 | |
blanchedalmond | #FFEBCD | 255,235,205 | |
blue | #0000FF | 0,0,255 | |
blueviolet | #8A2BE2 | 138,43,226 | |
brown | #A52A2A | 165,42,42 | |
burlywood | #DEB887 | 222,184,135 | |
cadetblue | #5F9EA0 | 95,158,160 | |
chartreuse | #7FFF00 | 127,255,0 | |
chocolate | #D2691E | 210,105,30 | |
coral | #FF7F50 | 255,127,80 | |
cornflowerblue | #6495ED | 100,149,237 | |
cornsilk | #FFF8DC | 255,248,220 | |
crimson | #DC143C | 220,20,60 | |
cyan | #00FFFF | 0,255,255 | |
darkblue | #00008B | 0,0,139 | |
darkcyan | #008B8B | 0,139,139 | |
darkgoldenrod | #B8860B | 184,134,11 | |
darkgray/darkgrey | #A9A9A9 | 169,169,169 | |
darkgreen | #006400 | 0,100,0 | |
darkkhaki | #BDB76B | 189,183,107 | |
darkmagenta | #8B008B | 139,0,139 | |
darkolivegreen | #556B2F | 85,107,47 | |
darkorange | #FF8C00 | 255,140,0 | |
darkorchid | #9932CC | 153,50,204 | |
darkred | #8B0000 | 139,0,0 | |
darksalmon | #E9967A | 233,150,122 | |
darkseagreen | #8FBC8F | 143,188,143 | |
darkslateblue | #483D8B | 72,61,139 | |
darkslategray/darkslategrey | #2F4F4F | 47,79,79 | |
darkturquoise | #00CED1 | 0,206,209 | |
darkviolet | #9400D3 | 148,0,211 | |
deeppink | #FF1493 | 255,20,147 | |
deepskyblue | #00BFFF | 0,191,255 | |
dimgray/dimgrey | #696969 | 105,105,105 | |
dodgerblue | #1E90FF | 30,144,255 | |
firebrick | #B22222 | 178,34,34 | |
floralwhite | #FFFAF0 | 255,250,240 | |
forestgreen | #228B22 | 34,139,34 | |
fuchsia | #FF00FF | 255,0,255 | |
gainsboro | #DCDCDC | 220,220,220 | |
ghostwhite | #F8F8FF | 248,248,255 | |
gold | #FFD700 | 255,215,0 | |
goldenrod | #DAA520 | 218,165,32 | |
gray/grey | #808080 | 128,128,128 | |
green | #008000 | 0,128,0 | |
greenyellow | #ADFF2F | 173,255,47 | |
honeydew | #F0FFF0 | 240,255,240 | |
hotpink | #FF69B4 | 255,105,180 | |
indianred | #CD5C5C | 205,92,92 | |
indigo | #4B0082 | 75,0,130 | |
ivory | #FFFFF0 | 255,255,240 | |
khaki | #F0E68C | 240,230,140 | |
lavender | #E6E6FA | 230,230,250 | |
lavenderblush | #FFF0F5 | 255,240,245 | |
lawngreen | #7CFC00 | 124,252,0 | |
lemonchiffon | #FFFACD | 255,250,205 | |
lightblue | #ADD8E6 | 173,216,230 | |
lightcoral | #F08080 | 240,128,128 | |
lightcyan | #E0FFFF | 224,255,255 | |
lightgoldenrodyellow | #FAFAD2 | 250,250,210 | |
lightgray/lightgrey | #D3D3D3 | 211,211,211 | |
lightgreen | #90EE90 | 144,238,144 | |
lightpink | #FFB6C1 | 255,182,193 | |
lightsalmon | #FFA07A | 255,160,122 | |
lightseagreen | #20B2AA | 32,178,170 | |
lightskyblue | #87CEFA | 135,206,250 | |
lightslategray/lightslategrey | #778899 | 119,136,153 | |
lightsteelblue | #B0C4DE | 176,196,222 | |
lightyellow | #FFFFE0 | 255,255,224 | |
lime | #00FF00 | 0,255,0 | |
limegreen | #32CD32 | 50,205,50 | |
linen | #FAF0E6 | 250,240,230 | |
magenta | #FF00FF | 255,0,255 | |
maroon | #800000 | 128,0,0 | |
mediumaquamarine | #66CDAA | 102,205,170 | |
mediumblue | #0000CD | 0,0,205 | |
mediumorchid | #BA55D3 | 186,85,211 | |
mediumpurple | #9370DB | 147,112,219 | |
mediumseagreen | #3CB371 | 60,179,113 | |
mediumslateblue | #7B68EE | 123,104,238 | |
mediumspringgreen | #00FA9A | 0,250,154 | |
mediumturquoise | #48D1CC | 72,209,204 | |
mediumvioletred | #C71585 | 199,21,133 | |
midnightblue | #191970 | 25,25,112 | |
mintcream | #F5FFFA | 245,255,250 | |
mistyrose | #FFE4E1 | 255,228,225 | |
moccasin | #FFE4B5 | 255,228,181 | |
navajowhite | #FFDEAD | 255,222,173 | |
navy | #000080 | 0,0,128 | |
oldlace | #FDF5E6 | 253,245,230 | |
olive | #808000 | 128,128,0 | |
olivedrab | #6B8E23 | 107,142,35 | |
orange | #FFA500 | 255,165,0 | |
orangered | #FF4500 | 255,69,0 | |
orchid | #DA70D6 | 218,112,214 | |
palegoldenrod | #EEE8AA | 238,232,170 | |
palegreen | #98FB98 | 152,251,152 | |
paleturquoise | #AFEEEE | 175,238,238 | |
palevioletred | #DB7093 | 219,112,147 | |
papayawhip | #FFEFD5 | 255,239,213 | |
peachpuff | #FFDAB9 | 255,218,185 | |
peru | #CD853F | 205,133,63 | |
pink | #FFC0CB | 255,192,203 | |
plum | #DDA0DD | 221,160,221 | |
powderblue | #B0E0E6 | 176,224,230 | |
purple | #800080 | 128,0,128 | |
rebeccapurple | #663399 | 102,51,153 | |
red | #FF0000 | 255,0,0 | |
rosybrown | #BC8F8F | 188,143,143 | |
royalblue | #4169E1 | 65,105,225 | |
saddlebrown | #8B4513 | 139,69,19 | |
salmon | #FA8072 | 250,128,114 | |
sandybrown | #F4A460 | 244,164,96 | |
seagreen | #2E8B57 | 46,139,87 | |
seashell | #FFF5EE | 255,245,238 | |
sienna | #A0522D | 160,82,45 | |
silver | #C0C0C0 | 192,192,192 | |
skyblue | #87CEEB | 135,206,235 | |
slateblue | #6A5ACD | 106,90,205 | |
slategray/slategrey | #708090 | 112,128,144 | |
snow | #FFFAFA | 255,250,250 | |
springgreen | #00FF7F | 0,255,127 | |
steelblue | #4682B4 | 70,130,180 | |
tan | #D2B48C | 210,180,140 | |
teal | #008080 | 0,128,128 | |
thistle | #D8BFD8 | 216,191,216 | |
tomato | #FF6347 | 255,99,71 | |
turquoise | #40E0D0 | 64,224,208 | |
violet | #EE82EE | 238,130,238 | |
wheat | #F5DEB3 | 245,222,179 | |
white | #FFFFFF | 255,255,255 | |
whitesmoke | #F5F5F5 | 245,245,245 | |
yellow | #FFFF00 | 255,255,0 | |
yellowgreen | #9ACD32 | 154,205,50 | |
-ro-comment-highlight | #FFFF0B | 255,255,11 | |
-ro-comment-underline | #23FF06 | 35,255,6 | |
-ro-comment-strikeout | #FB0007 | 251,0,7 |
Counter style name | 1 | 12 | 123 | 1234 |
decimal |
|
|
|
|
decimal-leading-zero |
|
|
|
|
super-decimal |
|
|
|
|
upper-hexadecimal |
|
|
|
|
lower-hexadecimal |
|
|
|
|
octal |
|
|
|
|
binary |
|
|
|
|
upper-roman |
|
|
|
|
lower-roman |
|
|
|
|
upper-alpha |
|
|
|
|
lower-alpha |
|
|
|
|
arabic-indic |
|
|
|
|
armenian |
|
|
|
|
upper-armenian |
|
|
|
|
lower-armenian |
|
|
|
|
bengali |
|
|
|
|
cambodian |
|
|
|
|
devanagari |
|
|
|
|
georgian |
|
|
|
|
upper-greek |
|
|
|
|
lower-greek |
|
|
|
|
gujarati |
|
|
|
|
gurmukhi |
|
|
|
|
hebrew |
|
|
|
|
hiragana |
|
|
|
|
hiragana-iroha |
|
|
|
|
japanese-formal |
|
|
|
|
japanese-informal |
|
|
|
|
kannada |
|
|
|
|
katakana |
|
|
|
|
katakana-iroha |
|
|
|
|
khmer |
|
|
|
|
lao |
|
|
|
|
upper-latin |
|
|
|
|
lower-latin |
|
|
|
|
malayalam |
|
|
|
|
mongolian |
|
|
|
|
myanmar |
|
|
|
|
oriya |
|
|
|
|
persian |
|
|
|
|
simp-chinese-formal |
|
|
|
|
simp-chinese-informal |
|
|
|
|
telugu |
|
|
|
|
thai |
|
|
|
|
tibetan |
|
|
|
|
urdu |
|
|
|
|
-ro-footnote |
|
|
|
|
-ro-spelled-out-en |
|
|
|
|
-ro-spelled-out-en-ordinal |
|
|
|
|
-ro-spelled-out-de |
|
|
|
|
-ro-spelled-out-fr |
|
|
|
|
The following lists all valid input/output value pairs for the transliterate
option of
,
according to the underlying ICU4J implementation.
PDFreactor supports the following CSS properties and functions.
Value: | [ <integer> && [<string> | <identifier>] ]# |
Initial: | 0 "" |
Applies To: | @counter-style |
Inherited: | No |
Value: | normal | [first | last]? baseline | stretch | space-between | space-around | space-evenly | [safe | unsafe]? [start | center | end | flex-start | flex-end] |
Initial: | normal |
Applies To: | block containers, flex containers and grid containers |
Inherited: | No |
Value: | normal | stretch | [first | last]? baseline | [safe | unsafe]? [center | start | end | self-start | self-end | flex-start | flex-end] |
Initial: | normal |
Inherited: | No |
Value: | auto | normal | stretch | [first | last]? baseline | [safe | unsafe]? [center | start | end | self-start | self-end | flex-start | flex-end] |
Initial: | auto |
Applies To: | flex items, grid items and absolutely-positioned boxes |
Inherited: | No |
Value: | initial | inherit | unset |
Initial: | |
Inherited: | No |
Value: | auto | none | <string> |
Initial: | auto |
Inherited: | No |
The alternate text is not specified and will be determined by other means, if necessary.
Deprecated synonym of auto.
Specific alternate text for the element. Often specified via the attr function, e.g. attr(src)
Value: | none | <string>+ |
Initial: | none |
Inherited: | No |
The element is not an anchor.
The element is an anchor with the given name.
Value: | none | <length>{1,2} | [ <page-size> || [ portrait | landscape] ] | media | trim | crop |
Initial: | none |
Applies To: | @page |
Inherited: | No |
The element does not specify an ArtBox.
The ArtBox is specified with the same dimensions as the MediaBox.
The ArtBox is specified with the same dimensions as the TrimBox.
The ArtBox is specified with the same dimensions as the CropBox.
Value: | none | [ <string> | content() ]+ |
Initial: | none |
Applies To: | all elements |
Inherited: | No |
Does not set a author.
Sets the specified string as author.
Sets the author from the content of the element.
Value: | [ <bg-layer>, ]* <final-bg-layer> |
Initial: | see individual properties |
Inherited: | No |
Value: | <attachment># |
Initial: | scroll |
Inherited: | No |
The background is fixed with regard to the element itself and does not scroll with its contents. (It is effectively attached to the element's border.)
The background is fixed with regard to the viewport. For pages this means that the background is repeated on every page.
Value: | [ border-box | padding-box | content-box ]# |
Initial: | border-box |
Inherited: | No |
Value: | <color> |
Initial: | transparent |
Inherited: | No |
Value: | <bg-image># |
Initial: | none |
Inherited: | No |
Value: | <box># |
Initial: | padding-box |
Inherited: | No |
border-box | padding-box | content-box | -ro-page-box | -ro-bleed-box
Only valid for background-images of pages. The background is positioned relative to the page box (including the page margins)
Only valid for background-images of pages. The background is positioned relative to the bleed box.
Value: | <position># |
Initial: | 0% 0% |
Inherited: | No |
Value: | <repeat-style># |
Initial: | repeat |
Inherited: | No |
Value: | <bg-size># |
Initial: | auto |
Inherited: | No |
Value: | <'-ro-barcode-content'> && <'-ro-barcode-type'> |
Initial: | auto qrcode |
Inherited: | No |
Value: | none | mod10 | mod1010 | mod11 | mod1110 | mod43 | crc8 |
Initial: | none |
Inherited: | No |
Value: | <color> |
Initial: | black |
Inherited: | No |
Value: | auto | <string> |
Initial: | auto |
Inherited: | No |
Value: | code128 | [databar [stacked | omnidirectional-stacked | expanded | expanded-stacked | limited]?] | [databar-expanded stacked?] | databar-limited | ean-8 | upc-a | upc-e |
Initial: | code128 |
Inherited: | No |
Value: | auto | <string> | <url> |
Initial: | auto |
Inherited: | No |
Encodes the value of the href attribute of the replaced element and resolves its URL when possible. If the href attribute is not set, the text content of the element is used.
Encodes the passed string as is.
Encodes the URL, relative URLs are resolved according to the documents base URL.
Value: | auto | <integer> | L | M | Q | H |
Initial: | auto |
Inherited: | No |
Use the default ecc level.
Value: | auto | eci | hibc | gs1 |
Initial: | auto |
Inherited: | No |
Value: | <'font-family'> |
Initial: | sans-serif |
Inherited: | No |
Value: | <'font-size'> |
Initial: | 8pt |
Inherited: | No |
Value: | none | [<string> <string>?] |
Initial: | none |
Inherited: | No |
Value: | [[top | bottom] || [left | center | right]] | none |
Initial: | bottom center |
Inherited: | No |
Value: | normal | <length> |
Initial: | normal |
Inherited: | No |
Value: | enabled | disabled |
Initial: | disabled |
Inherited: | No |
Value: | auto | [<integer>{1,2} || [<length> | <percentage>]] |
Initial: | auto |
Inherited: | No |
Size value of the barcode.
Use the default size.
Sets the bar length of 1D barcodes.
Value: | none | [<integer> [<string> | <integer>]?] |
Initial: | none |
Inherited: | No |
Value: | none | <integer> |
Initial: | none |
Inherited: | No |
Value: | auto | <length> |
Initial: | auto |
Inherited: | No |
The module size or bar width.
Use the default size of the respective barcode type
Value: | <barcode-type> |
Initial: | qrcode |
Inherited: | No |
Value: | auto | <length> |
Initial: | auto |
Applies To: | @page |
Inherited: | No |
There is no bleed area round the TrimBox, except when crop marks are enabled, which causes a bleed width of 6pt.
The length of the bleed area on each side of the TrimBox.
Value: | auto | <length> |
Initial: | auto |
Applies To: | @page |
Inherited: | No |
Computes the length automatically and lets the bleed mark always end at the media box.
The absolute length of the bleed mark. Negative values are not allowed. A length of zero disables the bleed mark.
Value: | <length> |
Initial: | 0 |
Applies To: | @page |
Inherited: | No |
Specifies the gap as an absolute length.
Value: | <'width'> |
Initial: | auto |
Applies To: | Same as 'width', 'height' |
Inherited: | No |
Value: | [ <string> | <named-string> | <quote> | counter() | counters() | content() | target-text() | target-counters() | target-counter() ]+ |
Initial: | content(text) |
Inherited: | No |
Value: | none | <integer> |
Initial: | none |
Inherited: | No |
Do not create a bookmark.
An integer greater than 0, that indicates the level of the bookmark.
Value: | open | closed |
Initial: | open |
Applies To: | block-level elements |
Inherited: | No |
The bookmark is opened by default, showing the bookmarks of the next level.
The bookmark is closed by default, hiding the bookmarks of the next level.
Value: | true | false |
Initial: | false |
Applies To: | iframe |
Inherited: | No |
Value: | <line-width> || <line-style> || <color> |
Initial: | see individual properties |
Inherited: | No |
Value: | <border-width> || <border-style> || <color> |
Initial: | |
Inherited: | No |
Value: | <color>{1,2} |
Initial: | |
Inherited: | No |
Value: | <border-style>{1,2} |
Initial: | see individual properties |
Inherited: | No |
Value: | <border-width>{1,2} |
Initial: | |
Inherited: | No |
Value: | [<length> | <percentage>]{1,2} |
Initial: | 0 |
Applies To: | all elements (but see prose) |
Inherited: | No |
border-bottom-left-radius, border-bottom-right-radius, border-top-left-radius, border-top-right-radius
Value: | collapse | separate |
Initial: | separate |
Applies To: | 'table' and 'inline-table' elements |
Inherited: | Yes |
Value: | [ <color> ]{1,4} |
Initial: | see individual properties |
Inherited: | No |
Value: | <border-width> || <border-style> || <color> |
Initial: | see individual properties |
Inherited: | No |
border-inline-start, border-inline-end, border-block-start, border-block-end
Value: | <color> |
Initial: | currentColor |
Inherited: | No |
border-inline-start-color, border-inline-end-color, border-block-start-color, border-block-end-color
Value: | <border-style> |
Initial: | none |
Inherited: | No |
border-inline-start-style, border-inline-end-style, border-block-start-style, border-block-end-style
Value: | <border-width> |
Initial: | medium |
Inherited: | No |
border-inline-start-width, border-inline-end-width, border-block-start-width, border-block-end-width
Value: | <percentage> | <length> | auto |
Initial: | auto |
Inherited: | No |
Value: | [ <length> | <percentage> ]{1,4} [ / [ <length> | <percentage> ]{1,4} ]? |
Initial: | see individual properties |
Applies To: | all elements (but see prose) |
Inherited: | No |
Value: | <length> <length>? |
Initial: | 0 |
Applies To: | 'table' and 'inline-table' elements |
Inherited: | Yes |
Value: | [<length> | <percentage>]{1,2} |
Initial: | 0 |
Inherited: | No |
Value: | <border-style>{1,4} |
Initial: | see individual properties |
Inherited: | No |
Value: | <border-width> || <border-style> || <color> |
Initial: | see individual properties |
Inherited: | No |
Value: | <color> |
Initial: | currentColor |
Inherited: | No |
border-top-color, border-right-color, border-bottom-color, border-left-color
Value: | <border-style> |
Initial: | none |
Inherited: | No |
border-top-style, border-right-style, border-bottom-style, border-left-style
Value: | <border-width> |
Initial: | medium |
Inherited: | No |
border-top-width, border-right-width, border-bottom-width, border-left-width
Value: | <border-width>{1,4} |
Initial: | see individual properties |
Inherited: | No |
Value: | <length> | <percentage> | auto |
Initial: | auto |
Applies To: | positioned elements |
Inherited: | No |
Value: | slice | clone |
Initial: | slice |
Applies To: | all elements |
Inherited: | No |
Value: | none | [inset? && <length>{2,4} && <color>?]# |
Initial: | none |
Inherited: | No |
Value: | content-box | border-box |
Initial: | content-box |
Applies To: | all elements that accept width or height |
Inherited: | No |
Value: | auto | always | avoid | left | right | verso | recto | page | column | region | avoid-page | avoid-column | avoid-region |
Initial: | auto |
Applies To: | block-level elements |
Inherited: | No |
Value: | auto | avoid | avoid-page | avoid-column | avoid-region |
Initial: | auto |
Applies To: | block-level elements |
Inherited: | No |
Value: | top | bottom |
Initial: | top |
Applies To: | 'table-caption' elements |
Inherited: | Yes |
Value: | none | [ <color> || <'-ro-change-bar-align'> || [ <'-ro-change-bar-offset'> <'-ro-change-bar-width'>? ] ] [ / <'-ro-change-bar-name'>]? |
Initial: | |
Inherited: | No |
Value: | [ start | end | left | right | inside | outside ] || [ [ page || distribute-column ] | column ] |
Initial: | start page |
Inherited: | No |
The change bar is positioned to the left for left-to-right documents or to the right for right-to-left documents. This is the default direction.
The change bar is positioned to the right for left-to-right documents or to the left for right-to-left documents.
The change bar is positioned to the left.
The change bar is positioned to the right.
The change bar is positioned on the side that would be the inside of a book, i.e. on the right for left pages and on the left for right pages.
The change bar is positioned on the side that would be the outside of a book, i.e. on the left for left pages and on the right for right pages.
This only works if the change bars are set to be placed on the page. Optional setting that enables a special behavior of change bars for elements in multi-column contexts, where they are placed on the page side that is closer to its respective column. If the distance is equal, the specified direction is used.
Sets that the base position of the change bars should always be the page margin. This is default behavior.
If set and the change bar creating element is inside a multi-column context, the change bar is rendered next to the column instead of inside the page margin.
Value: | none | <color> |
Initial: | none |
Inherited: | No |
There is no change bar for this element.
A change bar of the specified color is created for this element.
Value: | none | all | <identifier># |
Initial: | none |
Inherited: | No |
Value: | none | <identifier> |
Initial: | none |
Inherited: | No |
Value: | <length> | <percentage> |
Initial: | 25% |
Inherited: | No |
Value: | <border-width> |
Initial: | medium |
Inherited: | No |
Value: | none | left | right | inline-start | inline-end | both |
Initial: | none |
Inherited: | No |
Value: | <shape> | auto |
Initial: | auto |
Applies To: | absolutely positioned elements |
Inherited: | No |
The element does not clip.
In CSS 2.1, the only valid <shape> value is: rect(<top>, <right>, <bottom>, <left>) where <top> and <bottom> specify offsets from the top border edge of the box, and <right>, and <left> specify offsets from the left border edge of the box. Authors should separate offset values with commas. <top>, <right>, <bottom>, and <left> may either have a <length> value or 'auto'. Negative lengths are permitted. The value 'auto' means that a given edge of the clipping region will be the same as the edge of the element's generated border box (i.e., 'auto' means the same as '0' for <top> and <left>, the same as the used value of the height plus the sum of vertical padding and border widths for <bottom>, and the same as the used value of the width plus the sum of the horizontal padding and border widths for <right>, such that four 'auto' values result in the clipping region being the same as the element's border box).
Value: | <clip-source> | [ <basic-shape> || <geometry-box> ] | none |
Initial: | none |
Inherited: | No |
An URL to the <clipPath> element within an SVG which outlines the shape to be clipped.
A CSS function describing a shape as defined in the CSS Shapes module. This can be inset(), circle(), ellipse(), or polygon().
If used in combination with a basic shape, it provides the reference box according to which the shape is drawn. If used by itself, the edges of the specified box are used, including any corner shaping. Valid values are: border-box, padding-box, content-box, margin-box, fill-box, stroke-box and view-box. For elements with associated CSS layout box, the used value for fill-box is content-box and for stroke-box and view-box is border-box.
Value: | <color> |
Initial: | black |
Inherited: | Yes |
Value: | <length> | <percentage> |
Initial: | 100% |
Applies To: | @page |
Inherited: | No |
Specifies the gap as an absolute length.
Specifies the gap as a percentage value relative to the bleed. A value of 100% positions the inner side of the color bar exactly at the outer edge of the bleed.
Value: | gradient-tint | progressive-color | [<color>]+ | none |
Initial: | none |
Applies To: | @page |
Inherited: | No |
Defines a set of 11 grayscale colors, starting with a CMYK value of 0% each and raising the cyan, magenta and yellow values by 10% on every step.
Defines a set including solid process colors (cyan, magenta, yellow, black), solid overprint colors (cyan & magenta, cyan & yellow, magenta & yellow) and a 50% tint of each of the process colors.
One or more colors which will be sequentially painted from left to right or from top to bottom respectively.
Value: | none | auto |
Initial: | none |
Applies To: | multicol containers |
Inherited: | No |
The browser behavior, as described by the CSS specifications. Content inside a column may overflow into the next column.
The legacy behavior, as it was described in earlier versions of the CSS specifications. Content inside the columns is clipped horizontally, if it would overflow into the next column.
Value: | <integer> | auto |
Initial: | auto |
Applies To: | block containers |
Inherited: | No |
Value: | balance | balance-all | auto |
Initial: | balance |
Applies To: | multicol elements |
Inherited: | No |
Value: | <length> | <percentage> | normal |
Initial: | normal |
Applies To: | multi-column containers and grid containers |
Inherited: | No |
Value: | <'column-rule-width'> || <'column-rule-style'> || [ <'column-rule-color'> ] |
Initial: | see individual properties |
Applies To: | multicol elements |
Inherited: | No |
Value: | <color> | none |
Initial: | currentColor |
Applies To: | multicol elements |
Inherited: | No |
Value: | <border-style> | none |
Initial: | none |
Applies To: | multicol elements |
Inherited: | No |
Value: | <border-width> | <percentage> | none |
Initial: | medium |
Applies To: | multicol elements |
Inherited: | No |
Value: | none | all |
Initial: | none |
Applies To: | block-level elements, except floating and absolutely positioned elements |
Inherited: | No |
Value: | <length> | auto |
Initial: | auto |
Applies To: | block containers |
Inherited: | No |
Value: | [ <length> | auto ] || [ <integer> | auto ] |
Initial: | see individual properties |
Applies To: | block containers |
Inherited: | No |
Value: | auto | <color> |
Initial: | auto |
Inherited: | No |
The color depends on the value of the '-ro-comment-style' property: '-ro-comment-highlight' for 'note' and 'highlight', '-ro-comment-underline' for 'underline' and 'squiggly', '-ro-comment-strikeout' for 'strikeout'
The color of the comment.
Value: | none | [ <string> | content() ]+ |
Initial: | none |
Inherited: | No |
The comment receives no content.
Defines the content of the comment.
Defines the content of the comment from the content of the element.
Value: | auto | <string> |
Initial: | auto |
Inherited: | No |
The date of the comment is the current date.
The date of the comment, formatted according to the value of the "-ro-comment-dateformat" property.
Value: | <string> |
Initial: | "yyyy-MM-dd'T'kk:mm:ss" |
Inherited: | No |
The date format for the comment.
Value: | auto | page-left | page-right |
Initial: | auto |
Inherited: | No |
Shifts the note icon to the left side of the page.
Shifts the note icon to the right side of the page.
The note icon is placed next to the commented text.
Value: | none | [<string> [<string>]?] |
Initial: | none |
Inherited: | No |
The element is not a comment start or end element.
A unique identifier which links start and end element.
An optional second identifier to link start and end properties. This should only be used if the unique identifier is not unique for all elements but only for certain elements.
Value: | open | closed |
Initial: | closed |
Inherited: | No |
All comment bubbles will be opened and displayed when the document is opened in the PDF viewer.
All comment bubbles will be closed when the document is opened in the PDF viewer.
Value: | note | highlight | underline | strikeout | squiggly | invisible |
Initial: | note |
Inherited: | No |
Displays the comment as a note icon.
Highlights the background of the comment area in a certain color.
Underlines the text of the comment area with a straight line.
Strikes out the text of the comment area.
Underlines the text of the comment area with a squiggly line.
Does not visualize the comment in any way.
Value: | none | <string> |
Initial: | none |
Inherited: | No |
The comment receives no title.
Defines the title of the comment.
Value: | normal | none | [ <string> | <named-string> | <uri> | <gradient> | <quote> | counter() | -ro-counter-offset() | counters() | content() | target-text() | target-counters() | target-counter() | -ro-target-counter-offset() | leader() ]+ | <running-element> | <running-document> |
Initial: | normal |
Applies To: | :before and :after pseudo-elements as well as page-margin boxes |
Inherited: | No |
Named strings may be specified with the function: 'string()'. The string function has two arguments. The name of the named string as identifier and the location on the page (which is optional).
Running Elements may be specified with the function: 'element()' from a position property. The element function has two arguments. The name of the running element as identifier and the location on the page (which is optional).
Running documents may be specified with the proprietary function 'xhtml()', which takes an HTML string or a URL function.
Value: | none | [ <identifier> <integer>? ]+ |
Initial: | none |
Inherited: | No |
Value: | none | [ <identifier> <integer>? ]+ |
Initial: | none |
Inherited: | No |
Value: | none | [ <identifier> <integer>? ]+ |
Initial: | none |
Inherited: | No |
Value: | none | [ <identifier> <integer>? ]+ |
Initial: | none |
Inherited: | No |
Value: | auto | <length> |
Initial: | auto |
Applies To: | @page |
Inherited: | No |
Computes the length automatically and lets the crop mark always end at the media box.
The absolute length of the crop mark. Negative values are not allowed. A length of zero disables the crop mark.
Value: | <length> | <percentage> |
Initial: | 100% |
Applies To: | @page |
Inherited: | No |
Specifies the gap as an absolute length.
Specifies the gap as a percentage value relative to the bleed. A value of 100% positions the inner end point of the crop mark exactly at the outer edge of the bleed.
Value: | none | <length>{1,2} | [ <page-size> || [ portrait | landscape] ] | media | trim | art |
Initial: | none |
Applies To: | @page |
Inherited: | No |
The element does not specify a CropBox.
The CropBox is specified with the same dimensions as the MediaBox.
The CropBox is specified with the same dimensions as the TrimBox.
The CropBox is specified with the same dimensions as the ArtBox.
Value: | [self | expand | page] || [content-box | padding-box | border-box | margin-box | -ro-page-box | -ro-bleed-box | auto] || [<length> <length>?] |
Initial: | auto |
Inherited: | No |
The element itself is the target.
A parent of the element, determined based on the structure, is the target. (default)
The page the element is on is the target.
The layout box of the target to get the top left coordinate from.
The page box of the target to get the top left coordinate from. Matches margin-box for non-page targets, unless the target is a direct descendant of the page.
Matches -ro-page-box for page targets and border-box otherwise. (default)
Additional offset for the coordinate. May be negative. Using 2 lengths specifies x and y offsets separately. Defaults to 6pt.
Value: | ltr | rtl |
Initial: | ltr |
Applies To: | all elements |
Inherited: | Yes |
Value: | inline | block | list-item | inline-block | table | inline-table | table-row-group | table-column | table-column-group | table-header-group | table-footer-group | table-row | table-cell | table-caption | flex | inline-flex | grid | inline-grid | -ro-fast-table | none |
Initial: | inline |
Applies To: | all elements |
Inherited: | No |
This proprietary value is used to create very simple and fast tables. While these tables support only very basic styles and require all rows to have the same height, they can be extremely large without having a significantly impact on performance or memory consumption.
Value: | show | hide |
Initial: | show |
Applies To: | 'table-cell' elements |
Inherited: | Yes |
Value: | <identifier> |
Initial: | decimal |
Applies To: | @counter-style |
Inherited: | No |
Value: | [ <filter-function> ]+ | none |
Initial: | none |
Inherited: | No |
Value: | left | right | verso | recto | auto |
Initial: | auto |
Applies To: | @-ro-preferences |
Inherited: | No |
The first page is a left page.
The first page is a right page.
Same as 'left', unless the document direction is right-to-left, i.e. the root or body element has a 'direction' value of 'rtl', in which case it is the same as 'right'. This means that the first page is not a cover page.
Same as 'right', unless the document direction is right-to-left, i.e. the root or body element has a 'direction' value of 'rtl', in which case it is the same as 'left'. This means that the first page is a cover page.
Same as 'recto', unless the root or body element has a 'break-before' value of 'left', 'right' or 'verso', in which case it is the same as that value.
Value: | left | right | verso | recto | auto |
Initial: | auto |
Applies To: | @-ro-preferences |
Inherited: | No |
The first page is displayed left.
The first page is displayed right.
Same as 'left', unless the document direction is right-to-left, i.e. the root or body element has a 'direction' value of 'rtl', in which case it is the same as 'right'. This means that the first page is not displayed as a cover page.
Same as 'right', unless the document direction is right-to-left, i.e. the root or body element has a 'direction' value of 'rtl', in which case it is the same as 'left'. This means that the first page is displayed as a cover page.
Same as the used value of 'first-page-side'.
Value: | none | [ <'flex-grow'> <'flex-shrink'>? || <'flex-basis'> ] |
Initial: | 1 0 auto |
Applies To: | flex items |
Inherited: | No |
Value: | content | <'width'> |
Initial: | auto |
Applies To: | flex items |
Inherited: | No |
Value: | row | row-reverse | column | column-reverse |
Initial: | row |
Applies To: | flex containers |
Inherited: | No |
Value: | <'flex-direction'> || <'flex-wrap'> |
Initial: | row nowrap |
Applies To: | flex containers |
Inherited: | Yes |
Value: | <number> |
Initial: | 0 |
Applies To: | flex items |
Inherited: | No |
Value: | <number> |
Initial: | 1 |
Applies To: | flex items |
Inherited: | No |
Value: | nowrap | wrap | wrap-reverse |
Initial: | nowrap |
Applies To: | flex containers |
Inherited: | No |
Value: | none | left | right | inline-start | inline-end | -ro-top | -ro-bottom | footnote | -ro-sidenote() |
Initial: | none |
Applies To: | all elements |
Inherited: | No |
The element is taken out of flow and moved into a respective sidenote area, with its parameter defining whether that is the left or right sidenote area. This value can not be applied to generated content.
Value: | <length> | <percentage> |
Initial: | 0 |
Applies To: | page floats |
Inherited: | No |
Value: | auto | column | region | page |
Initial: | auto |
Applies To: | Footnote calls |
Inherited: | No |
On which fragmentainer (page, column or region) a footnote is placed is determined automatically. The current implementation always places footnotes on pages.
If the footnote call is located inside a multi-column element then the footnote is placed on the innermost column. If the footnote call it is not located inside a multi-column element then the footnote is placed on a page.
If the footnote call is located inside a region element then the footnote is placed on the innermost region. If the footnote call it is not located inside a region element then the footnote is placed on a page.
The footnote is placed on a page.
Value: | none | <identifier> |
Initial: | none |
Applies To: | Non-replaced block containers. |
Inherited: | No |
The block container is not a CSS Region.
The block container becomes a CSS Region, and is ordered in a region chain according to its document order.
Value: | none | <identifier> [element|content]? |
Initial: | none |
Applies To: | All elements, but not pseudo-elements such as ::first-line, ::first-letter, ::before or ::after. |
Inherited: | No |
The element is not moved to a named flow and normal CSS processing takes place.
If the keyword 'element' or neither keyword is present, the element is taken out of its parent's flow and placed into the named flow '<identifier>'. If the keyword 'content' is present, then only the element's contents is placed into the named flow. The values 'none', 'inherit', 'default', 'auto' and 'initial' are invalid flow names.
Value: | [ 'font-style' || 'font-variant' || 'font-weight' || 'font-stretch' ]? 'font-size' [ / 'line-height' ]? 'font-family' |
Initial: | see individual properties |
Applies To: | all elements and text |
Inherited: | No |
font-family, font-size, font-stretch, font-style, font-variant, font-weight, line-height
Value: | subset | all | none |
Initial: | subset |
Applies To: | @font-face |
Inherited: | No |
Only the subset or subsets that have glyphs being used in this document are embedded in the resulting PDF.
All subsets of this font are embedded, regardless of whether or not glyphs from these subsets are actually being used.
The font is not embedded in the document at all, even if glyphs from this font are being used.
Value: | [ <family-name> | <generic-family> ]# |
Initial: | serif |
Applies To: | all elements and text |
Inherited: | Yes |
Value: | <absolute-size> | <relative-size> | <length> | <percentage> |
Initial: | medium |
Applies To: | all elements and text |
Inherited: | Yes |
Value: | <number> | none | -ro-from-font |
Initial: | none |
Applies To: | all elements and text |
Inherited: | Yes |
Computes the x-height to font-size ratio of a particular font and sets it as the font-size-adjust value. This value will be inherited. Improves readability by ensuring that lowercase letters of text with a different font or text with a font fallback have the same height.
Value: | normal | ultra-condensed | extra-condensed | condensed | semi-condensed | semi-expanded | expanded | extra-expanded | ultra-expanded |
Initial: | normal |
Applies To: | all elements and text |
Inherited: | Yes |
Value: | normal | italic | oblique |
Initial: | normal |
Applies To: | all elements and text |
Inherited: | Yes |
Value: | none | [ weight || style ] |
Initial: | weight style |
Applies To: | All elements and text |
Inherited: | Yes |
Value: | auto | none |
Initial: | auto |
Applies To: | All elements and text |
Inherited: | Yes |
Value: | auto | none |
Initial: | auto |
Applies To: | all elements and text |
Inherited: | Yes |
Value: | normal | small-caps |
Initial: | normal |
Applies To: | all elements and text |
Inherited: | Yes |
Value: | normal | bold | bolder | lighter | <numerical-font-weight> |
Initial: | normal |
Applies To: | all elements and text |
Inherited: | Yes |
A number greater or equals to 1 and less or equal to 1000, where values of 400 or smaller are mapped to 'normal' and values of 500 or larger are mapped to 'bold'.
Value: | block | inline |
Initial: | block |
Applies To: | footnotes |
Inherited: | No |
The footnote element is placed in the footnote area as a block element. This is the default value.
The footnote element is placed in the footnote area as an inline element.
Value: | auto | none |
Initial: | auto |
Applies To: | root element, multi column elements and region elements |
Inherited: | Yes |
Value: | none | <string> |
Initial: | none |
Applies To: | Form elements |
Inherited: | No |
Value: | <'row-gap'> <'column-gap'>? |
Initial: | |
Applies To: | multi-column containers, flex containers and grid containers |
Inherited: | No |
Value: | auto | speed | quality |
Initial: | auto |
Inherited: | Yes |
Same as 'quality' except for pieces of text that are estimated not to require it, incl. most Latin text. (ligatures are not considered a requirement) or for Java versions older than 13.
Prioritizes performance, applying True Type Font kerning, but no more complex font features.
Enables Open Type Font kerning/positioning (required e.g. for Cambodian) and ligatures. It also causes characters in right-to-left text to be stored in PDF output in the correct order for accessibility. This impacts performance and both performance and result depend on the Java version used. Not using the latest Java version is discouraged.
Value: | <'grid-template'> | <'grid-template-rows'> / [ auto-flow && dense? ] <'grid-auto-columns'>? | [ auto-flow && dense? ] <'grid-auto-rows'>? / <'grid-template-columns'> |
Initial: | none |
Applies To: | grid containers |
Inherited: | No |
Value: | <grid-line> [ / <grid-line> ]{0,3} |
Initial: | auto |
Applies To: | grid items and absolutely-positioned boxes whose containing block is a grid container |
Inherited: | No |
Value: | <track-size>+ |
Initial: | auto |
Applies To: | grid containers |
Inherited: | No |
Value: | [ row | column ] || dense |
Initial: | row |
Applies To: | grid containers |
Inherited: | No |
Value: | <track-size>+ |
Initial: | auto |
Applies To: | grid containers |
Inherited: | No |
Value: | <grid-line> [ / <grid-line> ]? |
Initial: | auto |
Applies To: | grid items and absolutely-positioned boxes whose containing block is a grid container |
Inherited: | No |
Value: | <grid-line> |
Initial: | auto |
Applies To: | grid items and absolutely-positioned boxes whose containing block is a grid container |
Inherited: | No |
Value: | <grid-line> |
Initial: | auto |
Applies To: | grid items and absolutely-positioned boxes whose containing block is a grid container |
Inherited: | No |
Value: | <grid-line> [ / <grid-line> ]? |
Initial: | auto |
Applies To: | grid items and absolutely-positioned boxes whose containing block is a grid container |
Inherited: | No |
Value: | <grid-line> |
Initial: | auto |
Applies To: | grid items and absolutely-positioned boxes whose containing block is a grid container |
Inherited: | No |
Value: | <grid-line> |
Initial: | auto |
Applies To: | grid items and absolutely-positioned boxes whose containing block is a grid container |
Inherited: | No |
Value: | none | [ <'grid-template-rows'> / <'grid-template-columns'> ] | [ <line-names>? <string> <track-size>? <line-names>? ]+ [ / <explicit-track-list> ]? |
Initial: | none |
Applies To: | grid containers |
Inherited: | No |
Value: | none | <string>+ |
Initial: | none |
Applies To: | grid containers |
Inherited: | No |
Value: | none | <track-list> | <auto-track-list> |
Initial: | none |
Applies To: | grid containers |
Inherited: | No |
Value: | none | <track-list> | <auto-track-list> |
Initial: | none |
Applies To: | grid containers |
Inherited: | No |
Value: | auto | <length> | <percentage> | min-content | max-content |
Initial: | auto |
Applies To: | all elements but non-replaced inline elements, table columns, and column groups |
Inherited: | No |
Value: | auto | none |
Initial: | none |
Applies To: | Form elements |
Inherited: | No |
Automatically adjusts the height of a form control if the contents' height exceeds the height defined for the form control.
Value: | <integer> | auto |
Initial: | auto |
Inherited: | Yes |
Value: | <integer> | auto |
Initial: | auto |
Inherited: | Yes |
Value: | <string> | auto |
Initial: | auto |
Inherited: | Yes |
Value: | no-limit | <integer> |
Initial: | no-limit |
Applies To: | block containers |
Inherited: | Yes |
Value: | none | manual | auto |
Initial: | manual |
Inherited: | Yes |
Value: | none | auto | from-image |
Initial: | none |
Inherited: | Yes |
Ignore clip path in image metadata.
Automatically decide whether to read and apply clip path from image metadata based on the type of the image.
Read and apply clip path from image metadata.
Value: | auto | none |
Initial: | auto |
Applies To: | images (SVG and PDF) and SVG roots |
Inherited: | Yes |
Links in the image are clickable. (default)
Links in the image are not clickable.
Value: | from-image | none | <angle> | [ <angle>? flip ] |
Initial: | from-image |
Inherited: | Yes |
Ignore orientation data.
Read orientation data from image.
Angle (rounded to 90 degree increments) overriding orientation data.
When specified in addition to <angle> additional flip the image.
Value: | auto | [<compression-function> conditional?] |
Initial: | auto |
Inherited: | No |
Same as "jpeg() conditional".
Defines which compression algorithm should be used, either lossless or jpeg with an optional quality parameter.
If specified, the compression is only applied when -ro-image-resampling is used and the image is actually resampled, else the image is embedded without forced recompression.
Value: | auto | smooth | high-quality | pixelated | crisp-edges |
Initial: | auto |
Inherited: | Yes |
Image output: use bicubic interpolation, PDF output: enable interpolation flag if allowed
Image output: use bilinear interpolation, PDF output: enable interpolation flag if allowed
Image output: use bicubic interpolation, PDF output: enable interpolation flag if allowed
Image output: use nearest neighbor interpolation, PDF output: disable interpolation flag
Image output: use nearest neighbor interpolation, PDF output: disable interpolation flag
Value: | none | <resolution> |
Initial: | none |
Inherited: | No |
No resampling is applied to the image.
The maximum resolution of the image in the PDF. Allowed units are dpi, dpcm and dppx.
Value: | from-image || <resolution> |
Initial: | 1dppx |
Inherited: | Yes |
When specified the resolution is read from image metadata (allowing different resolutions for each dimension). If none is found falls back to the specified resolution or the default of 1dppx.
Value: | <integer> |
Initial: | 1 |
Applies To: | @-ro-preferences |
Inherited: | No |
Value: | auto | <percentage> | fit-page | fit-page-height | fit-page-width | fit-content | fit-content-height | fit-content-width |
Initial: | auto |
Applies To: | @-ro-preferences |
Inherited: | No |
The entire page is visible. In 2 column or 2 page mode this includes the width of both pages (see 'page-layout').
The page fills the view port height.
The page fills the view port width. In 2 column or 2 page mode this includes the width of both pages (see 'page-layout').
The content fills the complete view port.
The content fills the view port height.
The content fills the view port width.
Value: | [<length> | <percentage> | auto]{1,2} |
Initial: | see individual properties |
Inherited: | No |
Value: | normal | stretch | space-between | space-around | space-evenly | [safe | unsafe]? [start | center | end | flex-start | flex-end | left | right] |
Initial: | normal |
Applies To: | flex containers and grid containers |
Inherited: | No |
Value: | normal | stretch | [first | last]? baseline | [safe | unsafe]? [center | start | end | self-start | self-end | flex-start | flex-end | left | right] | legacy | legacy && [ left | right | center ] |
Initial: | legacy |
Inherited: | No |
Value: | auto | normal | stretch | [first | last]? baseline | [safe | unsafe]? [center | start | end | self-start | self-end | flex-start | flex-end | left | right] |
Initial: | auto |
Applies To: | block-level boxes, absolutely-positioned boxes and grid items |
Inherited: | No |
Value: | none | [ <string> | content() ]+ |
Initial: | none |
Applies To: | all elements |
Inherited: | No |
Does not set a keywords.
Sets the specified string as keywords.
Sets the keywords from the content of the element.
Value: | <length> | <percentage> | auto |
Initial: | auto |
Applies To: | positioned elements |
Inherited: | No |
Value: | normal | <length> |
Initial: | normal |
Inherited: | Yes |
Value: | normal || [ <whitelist>#? [ / <blacklist># ]? ] |
Initial: | normal |
Inherited: | Yes |
Use the line break opportunities defined by unicode specifications. This is the default value. If used together with whitelist/blacklist, both the unicode rules and the custom rules apply. If omitted only the custom rules apply.
One or two space separated regex strings that specify what content must surround a text position in order to make that position a line break opportunity. The first string describes the content before the break position, the second describes the content after it. The second string can be omitted, while the first string can be an empty string if it is not needed.
One or two space separated regex strings that specify what content must surround a break opportunity candidate in order to prevent it from becoming an actual line break opportunity. The first string describes the content before the position, the second describes the content after it. The second string can be omitted, while the first string can be an empty string if it is not needed. The blacklist takes precedence over the whitelist.
Value: | match-parent | create |
Initial: | match-parent |
Applies To: | block containers |
Inherited: | No |
Box assumes the line grid of its parent.
Box creates a new line grid using its own font and line layout settings.
Value: | normal | <number> | <length> | <percentage> |
Initial: | normal |
Inherited: | Yes |
Value: | none | baseline | contain |
Initial: | none |
Inherited: | Yes |
Line boxes do not snap to the grid; they stack normally.
The baseline snaps to the line grid applied to the element.
Two baselines are used to align the line box: the line box is snapped so that its central baseline is centered between two of the line grid's baselines.
Value: | auto | none | [ <string> ]+ |
Initial: | auto |
Applies To: | all elements |
Inherited: | No |
The element is not a hyperlink.
The element is a hyperlink to the URL the <string> contains.
The element is not a hyperlink, unless it is a QRcode, video or audio element.
Value: | all | all-block | content | content-block | block |
Initial: | all |
Inherited: | No |
Makes the border-areas of all elements in the subtree of the link clickable.
Like 'all', but merges the bounds of all areas into one clickable rectangle.
Makes the border-areas of all content elements (text, images and empty inlines) in the subtree of the link clickable.
Like 'content', but merges the bounds of all areas into one clickable rectangle.
Makes only the border-area of the link element itself clickable.
Value: | <'list-style-position'> || <'list-style-image'> || <'list-style-type'> |
Initial: | see individual properties |
Applies To: | elements with 'display: list-item' |
Inherited: | Yes |
Value: | <uri> | <gradient> | none |
Initial: | none |
Applies To: | elements with 'display: list-item' |
Inherited: | Yes |
Value: | inside | outside |
Initial: | outside |
Applies To: | elements with 'display: list-item' |
Inherited: | Yes |
Value: | <counter-style> | <string> | none |
Initial: | disc |
Applies To: | elements with 'display: list-item' |
Inherited: | Yes |
Value: | <integer> | auto |
Initial: | auto |
Applies To: | list-item |
Inherited: | No |
The number used for an ordered list item.
The number is the number of the previous item plus one (or one if it is the first item).
Use counter-set instead.
Value: | [ <length> | <percentage> | auto ]{1,4} |
Initial: | see individual properties |
Applies To: | all elements except elements with table display types other than table-caption, table and inline-table |
Inherited: | No |
Value: | [ <length> | <percentage> | auto ]{1,2} |
Initial: | |
Inherited: | No |
Value: | <length> | <percentage> | auto |
Initial: | 0 |
Inherited: | No |
margin-inline-start, margin-inline-end, margin-block-start, margin-block-end
Value: | <length> | <percentage> | auto |
Initial: | 0 |
Applies To: | all elements except elements with table display types other than table-caption, table and inline-table |
Inherited: | No |
Value: | match-self | match-parent |
Initial: | match-self |
Applies To: | list items |
Inherited: | Yes |
Value: | none | [ trim || bleed || registration ] |
Initial: | none |
Applies To: | @page |
Inherited: | No |
No marks are added to the page.
Adds trim line marks to the four corners of the page.
Adds bleed line marks to the four corners of the page.
Adds registration marks to the four sides of the page.
Use marks instead.
Value: | none | [ crop || cross || -ro-bleed] |
Initial: | none |
Applies To: | @page |
Inherited: | No |
No marks are added to the page.
Adds trim line marks to the four corners of the page.
Adds bleed line marks to the four corners of the page.
Adds registration marks to the four sides of the page.
Value: | <color> |
Initial: | cmyk(0%, 0%, 0%, 100%) |
Applies To: | @page |
Inherited: | No |
Value: | <length> | <percentage> |
Initial: | 100% |
Applies To: | @page |
Inherited: | No |
Value: | none | <length> |
Initial: | 0.5pt |
Applies To: | @page |
Inherited: | No |
Value: | <'max-width'> |
Initial: | none |
Applies To: | same as width and height |
Inherited: | No |
Value: | none | <length> | <percentage> | min-content | max-content |
Initial: | none |
Applies To: | all elements but non-replaced inline elements, table columns, and column groups |
Inherited: | No |
Specifies a fixed maximum computed height.
Specifies a percentage for determining the used value. The percentage is calculated with respect to the height of the generated box's containing block. If the height of the containing block is not specified explicitly (i.e., it depends on content height), and this element is not absolutely positioned, the percentage value is treated as 'none'.
No limit on the height of the box.
Behaves like 'none'.
Behaves like 'none'
Value: | none | <length> | <percentage> | min-content | max-content |
Initial: | none |
Applies To: | all elements but non-replaced inline elements, table rows, and row groups |
Inherited: | No |
Value: | none | <length>{1,2} | auto | [ <page-size> || [ portrait | landscape] ] |
Initial: | none |
Applies To: | @page |
Inherited: | No |
Value: | <'min-width'> |
Initial: | auto |
Applies To: | same as width and height |
Inherited: | No |
Value: | auto | <length> | <percentage> | min-content | max-content |
Initial: | auto |
Applies To: | all elements but non-replaced inline elements, table columns, and column groups |
Inherited: | No |
Value: | auto | <length> | <percentage> | min-content | max-content |
Initial: | auto |
Applies To: | all elements but non-replaced inline elements, table rows, and row groups |
Inherited: | No |
Value: | normal | multiply | screen | overlay | darken | lighten | color-dodge | color-burn | hard-light | soft-light | difference | exclusion | hue | saturation | color | luminosity |
Initial: | normal |
Inherited: | No |
Value: | [<string> | <identifier>] [<string> | <identifier>]? |
Initial: | "-" |
Applies To: | @counter-style |
Inherited: | No |
Value: | fill | contain | cover | none | scale-down |
Initial: | fill |
Applies To: | Replaced Elements |
Inherited: | No |
Value: | <position> |
Initial: | 50% 50% |
Applies To: | replaced elements |
Inherited: | No |
Value: | none | auto | avoid |
Initial: | none |
Applies To: | Block replaced-elements |
Inherited: | No |
Default. Images are not split.
Images are split at page breaks.
Images are split at page breaks, unless they fit on the next page.
Value: | <length> | <percentage> | auto |
Initial: | auto |
Applies To: | positioned elements |
Inherited: | No |
inset-inline-start, inset-inline-end, inset-block-start, inset-block-end
Value: | <alphavalue> |
Initial: | 1 |
Inherited: | No |
Value: | <integer> |
Initial: | 0 |
Applies To: | flex items and grid items |
Inherited: | No |
Value: | <integer> |
Initial: | 2 |
Applies To: | block container elements |
Inherited: | Yes |
Value: | [ 'outline-color' || 'outline-style' || 'outline-width' ] |
Initial: | see individual properties |
Inherited: | No |
Value: | <color> |
Initial: | currentColor |
Inherited: | No |
Value: | <length> |
Initial: | 0 |
Inherited: | No |
Value: | <border-style> |
Initial: | none |
Inherited: | No |
Value: | <border-width> |
Initial: | medium |
Inherited: | No |
Value: | visible | hidden | clip | scroll | auto |
Initial: | visible |
Applies To: | block containers |
Inherited: | No |
Value: | [content-box | padding-box | border-box] || <length> |
Initial: | 0px |
Inherited: | No |
Specifies the box of the element to use as the basis of the clip area. The default is padding-box.
Optionally increases the size of the clipping area in all directions. The value may not be negative. The defaults is 0.
Value: | normal | break-word | anywhere |
Initial: | normal |
Inherited: | Yes |
Value: | visible | hidden | clip | auto | scroll |
Initial: | visible |
Applies To: | block containers |
Inherited: | No |
Overflowing content is visible and the box is not made a block formatting context.
Overflowing content is clipped and the box is made a block formatting context.
Overflowing content is clipped and the box is made a block formatting context. In contrast to 'hidden' (and 'auto'), setting this value still allows the box to be aligned by its baseline.
Overflowing content is clipped and the box is made a block formatting context.
Overflowing content is visible in paged layouts and clipped otherwise, however the box is made a block formatting context in any case.
Value: | <integer> && [<string> | <identifier>] |
Initial: | 0 "" |
Applies To: | @counter-style |
Inherited: | No |
Value: | <padding-width>{1,4} |
Initial: | see individual properties |
Applies To: | all elements except table-row-group, table-header-group, table-footer-group, table-row, table-column-group and table-column |
Inherited: | No |
Value: | <padding-width>{1,2} |
Initial: | 0 |
Inherited: | No |
Value: | <padding-width> |
Initial: | 0 |
Inherited: | No |
padding-inline-start, padding-inline-end, padding-block-start, padding-block-end
Value: | <padding-width> |
Initial: | 0 |
Applies To: | all elements except table-row-group, table-header-group, table-footer-group, table-row, table-column-group and table-column |
Inherited: | No |
Value: | auto | <identifier> |
Initial: | auto |
Applies To: | boxes that create class 1 break points |
Inherited: | No |
The name of a particular page type. Page type names are case-sensitive identifiers.
Value: | auto | always | avoid | left | right |
Initial: | auto |
Applies To: | block-level elements |
Inherited: | No |
Value: | avoid | auto |
Initial: | auto |
Applies To: | block-level elements |
Inherited: | No |
Value: | bleed | media |
Initial: | bleed |
Applies To: | @page |
Inherited: | No |
Value: | auto | 1 column | 2 column | 1 page | 2 page |
Initial: | auto |
Applies To: | @-ro-preferences |
Inherited: | No |
Value: | <integer> |
Initial: | 0 |
Applies To: | @-ro-preferences |
Inherited: | No |
Value: | normal | avoid |
Initial: | normal |
Applies To: | floated, positioned and transformed elements |
Inherited: | No |
The stacking context layer to which an element is assigned is determined by default CSS rules. Floated elements without stacking context influencing styles (e.g. position or transform) are assigned to layer 4 (between block and inline). Transformed and positioned elements with stack level 0 (z-index 0 or auto) are assigned to layer 6 (after inline).
Disables the assignment to layer 4 for floated elements and layer 6 for positioned and transformed elements. Instead they are assigned to layer 3 (non-inline parts) or layer 5 (inline parts). This assignment is identical to the assignment they would have if the corresponding styles would not be present. This behavior is only applied if no other stacking context influencing styles with a higher priority are present, e.g. explicit z-index values or CSS filter functions.
Value: | auto | all | stylesheets-only | none |
Initial: | auto |
Applies To: | iframe, @page |
Inherited: | No |
Default value, all inheritable inline styles and all style sheets passed down to the embedded document.
Styles that have been set via the style-attribute (inline styles) are ignored, but the style sheets of the embedding document are passed down.
Styles are not passed down to the embedded document.
Whether the styles are passed down or not depends on the element (e.g. the styles are only passed down if the iframe is set to be seamless).
Value: | none | <string> |
Initial: | none |
Inherited: | No |
Value: | element | document |
Initial: | element |
Inherited: | No |
The attachment is related to the area of the element. Viewers may show a marker near that area.
The file is attached to the document with no relation to the element.
Value: | none | <string> |
Initial: | none |
Inherited: | No |
Value: | none | <url> | <string> |
Initial: | none |
Inherited: | No |
Value: | none | [multi-line || no-export || no-scroll || read-only || required || rich-text] |
Initial: | none |
Applies To: | Form elements |
Inherited: | No |
Allows text field content to occupy multiple lines. This is enabled by default for "textarea" elements.
Prevents the contents of the form field to be exported.
Disables horizontal scrolling inside a text field. This will also limit how much text content can be input in the field.
Prevents the form field from being filled or changed by user input.
Marks the form field as "required" which might be evaluated by PDF viewers or third party applications.
Allows the user to apply rich text formatting to the text field's contents.
Value: | none | <integer> |
Initial: | none |
Applies To: | Form elements |
Inherited: | No |
Specifies the maximum number of characters that the user can input.
Value: | none | pdf |
Initial: | none |
Applies To: | Form elements |
Inherited: | No |
The form element is not converted.
The form element is converted to an AcroForm.
Value: | auto | none | mode0 | mode1 |
Initial: | auto |
Inherited: | No |
No overprinting mode is specified. In general this means the mode is not changed compared to the parent.
Disables overprinting. Painting a new color, no matter in which color space, causes unspecified colorants to be erased at the corresponding positions. This means that in any area, only the color that was painted last is visible.
Standard overprint mode, also known as "OPM 0". In this mode source color component values replace values that have been previously painted for the corresponding device colorants, regardless what the new values are.
Illustrator overprint mode, also known as "OPM 1" or "nonzero overprint mode". When the overprint mode is 1, tint values of 0.0 for source color components do not change the corresponding components of previously painted colors.
Value: | [none | left | right | start | end | inside | outside | bottom]{1,2} |
Initial: | none |
Applies To: | @page |
Inherited: | No |
Value: | none | visual |
Initial: | visual |
Applies To: | @-ro-preferences |
Inherited: | No |
Enable visual optimization. Shapes are written to the PDF in a way to ensure a consistent look in certain PDF viewers. Without these modifications there may be different anti-aliasing for certain shapes.
Disable all shape optimizations.
Value: | [ none | all ] [ except <string># ]? |
Initial: | none |
Applies To: | Elements with a PDF signature field |
Inherited: | No |
Signing the field does not lock any form elements.
Signing the field locks all form elements in the document.
When followed by a list of strings, those are exceptions from 'none' or 'all', locking those fields or excluding them from locking respectively.
Value: | none | <string> |
Initial: | none |
Inherited: | No |
No PDF signature field is created.
A PDF signature field with the specified name is created. (names should be unique)
Value: | [ [ auto | aria-name | aria-description | <string> ]+ ]# | none |
Initial: | auto |
Inherited: | No |
Same as 'none'. "actual text" has to be specified explicitly.
The ARIA name of the element or the empty string if none can be determined
The ARIA description of the element or the empty string if none can be determined
A specific string or an attr function like attr(alt)
The element explicitly has no "actual text".
Value: | [ [ auto | aria-name | aria-description | <string> ]+ ]# | none |
Initial: | auto |
Inherited: | No |
First evaluates the property "-ro-alt-text". If that doesn't provide a result and the element is a replaced element, e.g. an image or barcode, the ARIA name and ARIA description are tried.
The ARIA name of the element or the empty string if none can be determined
The ARIA description of the element or the empty string if none can be determined
A specific string or an attr function like attr(alt)
The element explicitly has no alternative text. Also no last resort methods will be used to determine one.
Value: | [ [ auto | aria-name | aria-description | <string> ]+ ]# | none |
Initial: | auto |
Inherited: | No |
Same as 'none'. Expanded text has to be specified explicitly.
The ARIA name of the element or the empty string if none can be determined
The ARIA description of the element or the empty string if none can be determined
A specific string or an attr function like attr(alt)
The element explicitly has no expanded text.
Value: | text | button | radiobutton | checkbox |
Initial: | text |
Applies To: | Non-interactive form elements |
Inherited: | No |
The static form element is a text field.
The static form element is a button.
The static form element is a radio button.
The static form element is a checkbox.
Value: | off | on | neutral |
Initial: | off |
Applies To: | Non-interactive form elements |
Inherited: | No |
The element is unchecked.
The element is checked.
The element is half-checked.
Value: | [ [ auto | aria-name | aria-description | <string> ]+ ]# | none |
Initial: | auto |
Applies To: | Form elements |
Inherited: | No |
Tries the ARIA name and the ARIA description
The ARIA name of the element or the empty string if none can be determined
The ARIA description of the element or the empty string if none can be determined
A specific string or an attr function like attr(alt)
The element explicitly has no descriptive name. Also no last resort methods will be used to determine one.
Value: | auto | column | row |
Initial: | auto |
Inherited: | No |
Value: | [ [ auto | aria-name | aria-description | <string> ]+ ]# | none |
Initial: | auto |
Applies To: | Tables |
Inherited: | No |
Tries the ARIA name and the ARIA description
The ARIA name of the element or the empty string if none can be determined
The ARIA description of the element or the empty string if none can be determined
A specific string or an attr function like attr(alt)
The element explicitly has no summary. Also no last resort methods will be used to determine one.
Value: | <pdf-tag-type>{2}#? , [ auto | <pdf-tag-type> ]? |
Initial: | auto |
Inherited: | No |
Value: | auto | visual-only |
Initial: | auto |
Inherited: | Yes |
Text is embedded using fonts.
Text is rendered as vector graphics.
Value: | <'align-content'> <'justify-content'>? |
Initial: | normal |
Applies To: | multi-line flex containers |
Inherited: | No |
Value: | <'align-items'> <'justify-items'>? |
Initial: | |
Inherited: | No |
Value: | <'align-self'> <'justify-self'>? |
Initial: | auto |
Inherited: | No |
Value: | static | relative | absolute | fixed | running(<identifier>) |
Initial: | static |
Applies To: | all elements except table-column-group and table-column |
Inherited: | No |
Moves the element out of the normal flow and into a page margin box as a running header or footer. The page margin box needs to specify the element function with the same <identifier> used for the running element to display it.
Value: | normal | [ [ page | column ] || <box> ] |
Initial: | normal |
Applies To: | positioned elements |
Inherited: | No |
The element is positioned relative to its page. This value is used when only a <box> was specified.
When inside a multi-column element, the absolute positioned element is placed relative to the column. If the element is not inside a multi-column, it behaves like 'normal'.
Valid values are content-box, padding-box, border-box, -ro-page-box (this is the margin or trim box), -ro-bleed-box. The latter two are only valid for placing the element within the page.
Value: | [<string> | <identifier>] |
Initial: | "" |
Applies To: | @counter-style |
Inherited: | No |
Value: | L | M | Q | H |
Initial: | L |
Applies To: | QR Code elements |
Inherited: | No |
Low level error correction. Up to 7% damaged data can be restored.
Medium level error correction. Up to 15% damaged data can be restored.
Quartile level error correction. Up to 25% damaged data can be restored.
High level error correction. Up to 30% damaged data can be restored.
Use -ro-barcode instead.
Value: | normal | none |
Initial: | normal |
Applies To: | QR Code elements |
Inherited: | No |
QR code is black on white.
Instead of black, the value of the CSS property color is used to paint the squares. The background is visible instead of the white squares.
Use -ro-barcode instead.
Value: | normal | high |
Initial: | normal |
Applies To: | QR Code elements |
Inherited: | No |
The QR code is built from multiple squares.
The squares are combined into one object, ensuring a seamless look, at the cost of performance.
Use -ro-barcode instead.
Value: | <integer> |
Initial: | 1 |
Applies To: | QR Code elements |
Inherited: | No |
Possible values are 0 (no quiet zone) and positive integers.
Use -ro-barcode instead.
Value: | none | <string> |
Initial: | none |
Applies To: | Form elements |
Inherited: | No |
Value: | [ [ <integer> | infinite ]{2} ]# | auto |
Initial: | auto |
Applies To: | @counter-style |
Inherited: | No |
Value: | fallback | avoid | always |
Initial: | fallback |
Applies To: | SVG and Canvas elements |
Inherited: | Yes |
The SVG or Canvas is only rasterized when it uses features that are not supported by PDF vector graphics: masks, filters or non-default composites for SVG; non-default composites and ImageData access for Canvas.
Avoids rasterization of the entire SVG or Canvas by disabling functionality that is not supported by PDF vector graphics.
Rasterizes the Canvas in any case. (does not apply to SVG)
Value: | auto | none | <number> |
Initial: | auto |
Inherited: | Yes |
The default limit. Behaves the same as if the value was 2.
Disables the limit. This should be used with caution, especially if it is combined with "-ro-rasterization-supersampling", as large images have a significant impact on the required memory.
A number greater than zero which represents the maximum amount of pixels in millions (megapixels).
box-shadow, filter, -ro-rasterization-supersampling, text-shadow
Value: | <integer> |
Initial: | 2 |
Applies To: | Rasterized elements (see description) |
Inherited: | Yes |
The resolution of the rasterization is 96dpi multiplied by this factor. For example, a value of 2 means 192dpi. Accepted values are all positive integers, however, canvas will clip values larger than 4.
Value: | <length> | <percentage> |
Initial: | 100% |
Applies To: | @page |
Inherited: | No |
Specifies the gap as an absolute length.
Specifies the gap as a percentage value relative to the bleed. A value of 100% positions the inner side of the registration mark exactly at the outer edge of the bleed.
Value: | <length> |
Initial: | 0.5cm |
Applies To: | @page |
Inherited: | No |
Value: | none | image | barcode | qrcode | embedded-svg |
Initial: | none |
Inherited: | No |
Creates an image replaced element. Used in combination with -ro-source.
Creates a barcode replaced element. Used in combination with -ro-barcode-type.
Creates a legacy QR code replaced element. The QR code is read from an existing "href" attribute or the text content of the element.
Creates an SVG replaced element from embedded SVG content.
Value: | <length> | <percentage> | auto |
Initial: | auto |
Applies To: | positioned elements |
Inherited: | No |
Value: | <length> | <percentage> | normal |
Initial: | normal |
Applies To: | grid containers |
Inherited: | No |
Value: | <integer> |
Initial: | 1 |
Applies To: | table-cell elements |
Inherited: | No |
Value: | none | auto | <percentage> |
Initial: | none |
Applies To: | @page (first page only) |
Inherited: | No |
A percent value which is treated as a scaling factor for the content.
The scale factor is determined based on the content of the document, for the purpose of shrink-to-fit. It is ensured that no block overflows its respective page content width or height. (The entire document is analyzed to determine the required factor.)
Value: | <alphavalue> |
Initial: | 0 |
Applies To: | floats |
Inherited: | No |
Value: | <length> | <percentage> |
Initial: | 0 |
Applies To: | floats |
Inherited: | No |
Value: | none | [ <basic-shape> || <shape-box> ] | <image> | -ro-self |
Initial: | none |
Applies To: | floats |
Inherited: | No |
Similar to specifying an image, but the shape is derived from the float element's content, e.g. text is wrapped around a large letter. Also uses the value of shape-image-threshold.
Value: | [start | end | stack ] | [[baseline | container-start | container-end] strict?] |
Initial: | baseline |
Applies To: | Sidenotes |
Inherited: | No |
The baselines of the sidenote and its origin line should be at the same vertical position.
The sidenote's top should be placed at the same height as the block container element's top from which it originates. The border rectangles are used for this alignment.
The sidenote's bottom should be placed at the same height as the block container element's bottom from which it originates. The border rectangles are used for this alignment. Note that the sidenote may still be pushed down to avoid overlapping with a previous sidenote, so consider also setting 'strict' when using this alignment.
The sidenote will be placed directly under the previous sidenote (or at top if it is the first one). They are basically stacked on top of each other.
The sidenote will placed at the top of the sidenote area or directly below of previous start-aligned sidenotes. Note that start-aligned sidenotes will always be above sidenotes with any other alignment, no matter their DOM order.
The sidenote will placed at the bottom of the sidenote area or directly above of previous end-aligned sidenotes. Note that end-aligned sidenotes will always be below sidenotes with any other alignment, no matter their DOM order.
This value can only applies for alignments that depend on the sidenote's origin (e.g. 'baseline', but not 'start'). As long as there is enough space in the sidenote area, the sidenote will not be pushed away from its intended position. Overlapping is avoided by moving previous sidenotes up.
Value: | none | [ <box> || [ <sidenote-side> | both ] ] |
Initial: | none |
Inherited: | No |
The element's box that determines the vertical position and height that is considered as overlapping with sidenotes. Allowed values are 'border-box', 'padding-box', 'content-box' and 'margin-box'. If omitted, 'border-box' is used.
Accepts the same values as the -ro-sidenote() function.
Value: | <length> | <percentage> |
Initial: | 0 |
Applies To: | sidenotes |
Inherited: | No |
Value: | auto | <length>{1,2} | [ <page-size> || [ portrait | landscape] ] |
Initial: | auto |
Applies To: | @page |
Inherited: | No |
The page size is set to the given absolute dimensions. If only one length value is specified, it sets both the width and height of the page (i.e. it is a square). If two length values are specified, the first establishes the width, and the second one the height. Negative lengths are invalid.
The page size is set to a named one, like A4, A5, letter or legal. See the linked chapter for a full list of valid values. When no orientation is specified the default one is portrait.
Specifies that the named page size is oriented in landscape, i.e. the longer sides of the page are horizontal. If no '<page-size>' is specified, the default size A4 is used.
Specifies that the named page size is oriented in portrait, i.e. the shorter sides of the page are horizontal. If no '<page-size>' is specified, the default size A4 is used.
Equivalent to specifying A4.
Value: | none | <url> | [<string>]+ |
Initial: | none |
Inherited: | No |
Value: | auto | <string> |
Initial: | auto |
Inherited: | No |
Value: | <integer> |
Initial: | 1 |
Inherited: | No |
The number of the page that is shown, with 1 being the first page. Negative numbers count from the document end, with -1 being the last page. A value of 0 is treated like the default value, which is 1.
Value: | [ <identifier> [ <string> | <named-string> | <quote> | counter() | counters() | content() | target-text() | target-counters() | target-counter() ]+ ]# | none |
Initial: | none |
Inherited: | No |
a string, e.g. "foo"
counter() or counters() function
the 'content()' function returns the content of elements and pseudo-elements.
Value: | none | [ <string> | content() ]+ |
Initial: | none |
Applies To: | all elements |
Inherited: | No |
Does not set a subject.
Sets the specified string as subject.
Sets the subject from the content of the element.
Value: | [<string> | <identifier>] |
Initial: | "." |
Applies To: | @counter-style |
Inherited: | No |
Value: | [<string> | <identifier>]+ |
Initial: | "" |
Applies To: | @counter-style |
Inherited: | No |
Value: | cyclic | numeric | alphabetic | symbolic | additive | [ fixed <integer>? ] | [ extends <identifier> ] |
Initial: | symbolic |
Applies To: | @counter-style |
Inherited: | No |
Value: | <integer> |
Initial: | 8 |
Applies To: | block containers |
Inherited: | Yes |
Value: | auto | fixed |
Initial: | auto |
Applies To: | 'table' and 'inline-table' elements |
Inherited: | No |
Value: | none | all | counter | text |
Initial: | none |
Inherited: | No |
The text and counter data of the element can not be accessed from later segments.
The text and counter data of the element can be accessed from later segments.
The counter data of the element can be accessed from later segments.
The text of the element can be accessed from later segments.
Value: | start | end | left | right | center | justify | match-parent | justify-all |
Initial: | start |
Applies To: | block containers |
Inherited: | Yes |
Value: | start | end | left | right | center | justify | match-parent |
Initial: | start |
Applies To: | block containers |
Inherited: | Yes |
Value: | auto | start | end | left | right | center | justify |
Initial: | auto |
Applies To: | block containers |
Inherited: | Yes |
Value: | <'text-decoration-line'> || <'text-decoration-thickness'> || <'text-decoration-style'> || <'text-decoration-color'> |
Initial: | see individual properties |
Applies To: | all elements |
Inherited: | No |
Value: | <color> |
Initial: | currentColor |
Applies To: | all elements |
Inherited: | No |
Value: | none | [ underline || overline || line-through || blink ] |
Initial: | none |
Applies To: | all elements |
Inherited: | No |
Value: | solid | double | dotted | dashed |
Initial: | solid |
Applies To: | all elements |
Inherited: | No |
Value: | auto | from-font | <length> | <percentage> |
Initial: | auto |
Applies To: | all elements |
Inherited: | No |
Value: | <length> | <percentage> |
Initial: | 0 |
Applies To: | block containers |
Inherited: | Yes |
Value: | clip | ellipsis | -ro-scale-down |
Initial: | clip |
Applies To: | block containers |
Inherited: | No |
Visually reduces the size of the text until there is no more overflow. The origin of that scale transform depends on two other properties, 'direction' for its horizontal position, which is always on the start side, and 'align-content' for the vertical position, which can be 'start', 'end', 'center', 'baseline' (default) and 'stretch'. While the scale factor is based only on horizontal overflow, both directions are scaled by the same amount, except for a 'align-content' value of 'stretch', in which case there is only horizontal scaling.
Value: | none | [<string> <string> [[source | white-space | text-transform | shaped | hybrid-layout] || [strict | ignore-case | ignore-variants | regex | transliterate]]?]# |
Initial: | none |
Inherited: | Yes |
replacement point: before any other processing.
replacement point: after the "white-space" property was applied (default).
replacement point: after the "white-space" and "text-transform" properties were applied.
replacement point: after the "white-space" and "text-transform" properties as well as shaping (e.g. for Arabic) was applied.
replacement point: during inline layout, using the original character for logical and the replacement for visual parts of the layout. The replacement must have the same length as the original.
replacement method: simple case-sensitive (default).
replacement method: ignoring case as well as form (e.g. of Arabic characters due to shaping).
replacement method: ignoring variants of any kind, including case, form, accents and diaereses.
replacement method: using regular expression pattern.
replacement method: transliteration. Use scripts as input and output, e.g.: "any" "latin" transliterate
Value: | none | [ <length>{2,3} && <color>? ]# |
Initial: | none |
Applies To: | text |
Inherited: | Yes |
Value: | capitalize | uppercase | lowercase | none |
Initial: | none |
Applies To: | text |
Inherited: | Yes |
Value: | auto | <length> | <percentage> |
Initial: | auto |
Applies To: | all elements |
Inherited: | Yes |
Value: | auto | [ from-font | under ] |
Initial: | auto |
Applies To: | all elements |
Inherited: | Yes |
Value: | none | [ <string> | content() ]+ |
Initial: | none |
Applies To: | all elements |
Inherited: | No |
Does not set a title.
Sets the specified string as title.
Sets the title from the content of the element.
Value: | <length> | <percentage> | auto |
Initial: | auto |
Applies To: | positioned elements |
Inherited: | No |
Value: | none | <transform-function>+ |
Initial: | none |
Applies To: | transformable elements |
Inherited: | No |
Value: | [ left | center | right | top | bottom | <percentage> | <length> ] | [ left | center | right | <percentage> | <length> ] [ top | center | bottom | <percentage> | <length> ] | [[ center | left | right ] && [ center | top | bottom ]] |
Initial: | 50% 50% |
Applies To: | transformable elements |
Inherited: | No |
Value: | none | auto | always |
Initial: | auto |
Applies To: | pages, multi-column containers, regions, root elements of iframes |
Inherited: | Yes |
The margins are never truncated to zero.
The behavior defined by the CSS specifications. The margins are truncated to zero if the page break has not been forced. The margin on the first page and after a forced break is preserved.
The margins of blocks at the top of a page are always truncated to zero. This is the behavior of PDFreactor prior to version 9.
Value: | normal | embed | isolate | bidi-override | isolate-override | plaintext |
Initial: | normal |
Applies To: | all elements |
Inherited: | No |
The element does not open an additional level of embedding with respect to the bidirectional algorithm. For inline elements, implicit reordering works across element boundaries.
If the element is inline, this value opens an additional level of embedding with respect to the bidirectional algorithm. The direction of this embedding level is given by the 'direction' property. Inside the element, reordering is done implicitly. This corresponds to adding a LRE (U+202A; for 'direction: ltr') or RLE (U+202B; for 'direction: rtl') at the start of the element and a PDF (U+202C) at the end of the element.
For inline elements this creates an override. For block container elements this creates an override for inline-level descendants not within another block container element. This means that inside the element, reordering is strictly in sequence according to the 'direction' property; the implicit part of the bidirectional algorithm is ignored. This corresponds to adding a LRO (U+202D; for 'direction: ltr') or RLO (U+202E; for 'direction: rtl') at the start of the element or at the start of each anonymous child block box, if any, and a PDF (U+202C) at the end of the element.
This combines the isolation behavior of isolate with the directional override behavior of bidi-override: to surrounding content, it is equivalent to isolate, but within the box content is ordered as if bidi-override were specified. It effectively nests a directional override inside an isolated sequence.
This value behaves as isolate except that for the purposes of the Unicode bidirectional algorithm, the base directionality of each of the box’s bidi paragraphs (if a block container) or isolated sequences (if an inline) is determined by following the heuristic in rules P2 and P3 of the Unicode bidirectional algorithm (rather than by using the direction property of the box).
Value: | baseline | sub | super | top | text-top | middle | bottom | text-bottom | <percentage> | <length> |
Initial: | baseline |
Applies To: | inline-level and 'table-cell' elements |
Inherited: | No |
Value: | visible | hidden | collapse |
Initial: | visible |
Applies To: | all elements |
Inherited: | Yes |
Value: | normal | pre | nowrap | pre-wrap | pre-line |
Initial: | normal |
Applies To: | text |
Inherited: | Yes |
Value: | <integer> |
Initial: | 2 |
Applies To: | block container elements |
Inherited: | Yes |
Value: | auto | <length> | <percentage> | min-content | max-content | fit-content |
Initial: | auto |
Applies To: | all elements but non-replaced inline elements, table rows, and row groups |
Inherited: | No |
Value: | auto | none |
Initial: | none |
Applies To: | Form elements |
Inherited: | No |
Automatically adjusts the width of a form control if the contents' width exceeds the width defined for the form control.
Value: | normal | <length> | <percentage> |
Initial: | normal |
Inherited: | Yes |
Value: | <'overflow-wrap'> |
Initial: | normal |
Inherited: | Yes |
Value: | <integer> | auto |
Initial: | auto |
Applies To: | positioned elements and grid items |
Inherited: | No |
attr(<attr-name> <type-or-unit>? [ , <attr-fallback> ]?)
The attribute name
Specifies how the attribute should be interpreted. Default is 'string'.
If the attribute could not found, this value is used instead.
-ro-attr-ancestor(<attr-name> [ , <element-name> ]?)
The name of the attribute. Its value will be returned as a string. If it is not found, an empty string is returned.
If specified, the attribute value is retrieved from the closest ancestor element (or self) with that name or from the element itself if element-name matches. If no element is found, the original element itself is used.
blur(radius)
The radius of the blur. The blur can differ in x and y axis, by specifying a second length for the y axis. Negative values are not allowed.
brightness(factor)
calc(expression)
The mathematical expression. A whitespace is required on both sides of + and - operators. Several terms can be chained (e.g. calc(50% - 2cm + 8px); ).
circle([<shape-radius>]? [at <position>]?)
Defines the radius of the circle, closest-side if omitted. Valid identifiers are closest-side (uses the closest distance from the center of the circle to a border of the reference box) and farthest-side (uses the farthest distance to a border of the reference box). Negative values are invalid.
Determines the center of the circle. Uses the same syntax as the 'background-position' property. Default value is 'center'.
cmyk(cyan, magenta, yellow, key[, alpha]?)
Cyan color component. Number between 0 and 1 or percentage.
Magenta color component. Number between 0 and 1 or percentage.
Yellow color component. Number between 0 and 1 or percentage.
Key (usually black) color component. Number between 0 and 1 or percentage.
Alpha value of the color. Number between 0 and 1 or percentage.
content(text, before, after, first-letter)
The text content of the element. This is the default value.
The content of the ::before pseudo-element.
The content of the ::after pseudo-element.
The first-letter of the element's content text.
contrast(factor)
counter(<identifier> [, <counter-style> ]?)
The name of the counter
Specifies the style of the number. Default is 'decimal'.
-ro-counter-offset(<identifier>, <integer> [, <counter-style> ]?)
The name of the counter
The integer by which the counter value is modified.
Used to format the result, see the property 'list-style-type' for more information on the keywords. Default is 'decimal'.
counters(<identifier>, <string> [, <counter-style> ]?)
drop-shadow(<color>? && <length>{2,3})
element(<identifier> [ , [ first | start | last | first-except] ]?)
The name of the running element as identifier, which is specified using the position property with the running() function.
Keywords that, in a case where there are multiple assignments on a page, specify which one should be used.
ellipse([<shape-radius>{2}]? [at <position>]?)
Define the horizontal and vertical radius of the ellipse, in this order. They default to closest-side if omitted, negative values are invalid. Valid identifiers are closest-side (uses the distance from the ellipses center to the closest border of the reference box which is orthogonal to the respective radius) and farthest-side (uses the farthest distance to the respective border of the reference box).
Determines the center of the ellipse. Uses the same syntax as the 'background-position' property. Default value is 'center'.
gray(gray[, alpha]?)
The shade of gray. A number between 0 and 1 or percentage.
The alpha channel. A number between 0 and 1 or percentage.
grayscale(factor)
With a value of 1 or 100%, the element is in grayscale.
hsl(hue, saturation, lightness[, alpha]?)
The hue of the color. Set using an angle of the color circle. Number are interpreted as a number of degrees.
The saturation of the color.
The lightness of the color.
Alpha color component. Number between 0 and 1 or percentage.
hsla(hue, saturation, lightness[, alpha]?)
The hue of the color. Set using an angle of the color circle. Number are interpreted as a number of degrees.
The saturation of the color.
The lightness of the color.
The alpha channel.
hue-rotate(angle)
The color shift as an angle.
hwb([<number> | <angle> | none] [<percentage> | <number> | none] [<percentage> | <number> | none] [ / [<alphavalue> | none] ]?)
An <alphavalue> representing the alpha channel value of the color, where the number 0 corresponds to 0% (fully transparent) and 1 corresponds to 100% (fully opaque). Additionally, the keyword none can be used to explicitly specify no alpha channel. If the A channel value is not explicitly specified, it defaults to 100%. If included, the value is preceded by a slash (/).
A <percentage> or number representing the color's blackness or the keyword none (equivalent to 0% in this case) to mix in. 0% represents no blackness. 100% represents full blackness if whiteness is 0, otherwise both the whiteness and blackness values are normalized.
A <number>, an <angle>, or the keyword none (equivalent to 0deg in this case) representing the color's <hue> angle.
A <percentage> or number representing the color's whiteness or the keyword none (equivalent to 0% in this case) to mix in. 0% represents no whiteness. 100% represents full whiteness if blackness is 0, otherwise both the whiteness and blackness values are normalized.
inset(<shape-arg>{1,4} [round <border-radius>]?)
Defines the top, right, bottom and left offsets from the reference box. These arguments follow the syntax of the margin shorthand.
Defines rounded corners for the inset rectangle, using the border-radius shorthand syntax. Negative values are invalid.
invert(factor)
How strong the inversion should be. 50% makes the image gray, 100% completely inverts all colors.
jpeg([quality]?)
Defines the quality of the compressed image. Either a number between 0 and 1 or a percentage value between 0% and 100%. If omitted, the quality defaults to 80%.
lab([<percentage> | <number> | none] [ <percentage> | <number> | none] [ <percentage> | <number> | none] [ / [<alphavalue> | none] ]?)
A <number> between -125 and 125, a <percentage> between -100% and 100%, or the keyword none (equivalent to 0% in this case). This value specifies the color's distance along the a axis, which defines how green (moving towards -125) or red (moving towards +125) the color is. Note that these values are signed (allowing both positive and negative values) and theoretically unbounded, meaning that you can set values outside the ±125 (±100%) limits. In practice, values cannot exceed ±160.
An <alphavalue> representing the alpha channel value of the color, where the number 0 corresponds to 0% (fully transparent) and 1 corresponds to 100% (fully opaque). Additionally, the keyword none can be used to explicitly specify no alpha channel. If the A channel value is not explicitly specified, it defaults to 100%. If included, the value is preceded by a slash (/).
A <number> between -125 and 125, a <percentage> between -100% and 100%, or the keyword none (equivalent to 0% in this case). This value specifies the color's distance along the b axis, which defines how blue (moving towards -125) or yellow ( moving towards +125) the color is. Note that these values are signed (allowing both positive and negative values) and theoretically unbounded, meaning that you can set values outside the ±125 (±100%) limits. In practice, values cannot exceed ±160.
A <number> between 0 and 100, a <percentage> between 0% and 100%, or the keyword none (equivalent to 0% in this case). This value specifies the color's lightness. Here the number 0 corresponds to 0% (black) and the number 100 corresponds to 100% (white).
lch([<percentage> | <number> | none] [<percentage> | <number> | none] [<percentage> | <number> | <angle> | none] [ / [<alphavalue> | none] ]?)
An <alphavalue> representing the alpha channel value of the color, where the number 0 corresponds to 0% (fully transparent) and 1 corresponds to 100% (fully opaque). Additionally, the keyword none can be used to explicitly specify no alpha channel. If the alpha channel value is not explicitly specified, it defaults to 100%. If included, the value is preceded by a slash (/).
A <number>, a <percentage>, or the keyword none (equivalent to 0% in this case). This value is a measure of the color's chroma (roughly representing the "amount of color"). Its minimum useful value is 0%, or 0, while its maximum is theoretically unbounded (but in practice does not exceed 230), with 100% being equivalent to 150.
A <number>, an <angle>, or the keyword none (equivalent to 0deg) representing the color's <hue> angle.
A <number> between 0 and 100, a <percentage> between 0% and 100%, or the keyword none (equivalent to 0%). The number 0 corresponds to 0% (black), and the number 100 corresponds to 100% (white). This value specifies the color's brightness in the CIELab color space.
leader([dotted | solid | space] | <string>)
linear-gradient([ [ <angle> | to <side-or-corner> ] ,]? <color-stop>[, <color-stop>]+)
The angle of direction for the gradient.
The direction of the gradient, using keywords. Syntax is [ left | right ] || [ top | bottom ].
Defines the colors of the gradient. Syntax is "<color> [ <percentage> | <length>]?".
lossless()
minmax([ <fixed-breadth> , <track-breadth> ] | [ <inflexible-breadth> , <fixed-breadth> ] | [ <inflexible-breadth> , <track-breadth> ])
oklab([<percentage> | <number> | none] [ <percentage> | <number> | none] [<percentage> | <number> | none] [ / [<alphavalue> | none] ]?)
A <number> between -0.4 and 0.4, a <percentage> between -100% and 100%, or the keyword none (equivalent to 0% in this case). This value specifies the color's distance along the a axis in the Oklab color space, which defines how green (moving towards -0.4) or red (moving towards +0.4) the color is. Note that these values are signed (allowing both positive and negative values) and theoretically unbounded, meaning that you can set values outside the ±0.4 (±100%) limits. In practice, values cannot exceed ±0.5.
An <alphavalue> representing the alpha channel value of the color, where the number 0 corresponds to 0% (fully transparent) and 1 corresponds to 100% (fully opaque). Additionally, the keyword none can be used to explicitly specify no alpha channel. If the A channel value is not explicitly specified, it defaults to 100%. If included, the value is preceded by a slash (/).
A <number> between -0.4 and 0.4, a <percentage> between -100% and 100%, or the keyword none (equivalent to 0% in this case). This value specifies the color's distance along the b axis in the Oklab color space, which defines how blue (moving towards -0.4) or yellow (moving towards +0.4) the color is. Note that these values are signed (allowing both positive and negative values) and theoretically unbounded, meaning that you can set values outside the ±0.4 (±100%) limits. In practice, values cannot exceed ±0.5.
A <number> between 0 and 1, a <percentage> between 0% and 100%, or the keyword none (equivalent to 0% in this case). This value specifies the color's perceived lightness. The number 0 corresponds to 0% (black) and the number 1 corresponds to 100% (white).
oklch([<percentage> | <number> | none] [<percentage> | <number> | none] [<percentage> | <number> | <angle> | none] [ / [<alphavalue> | none] ]?)
An <alphavalue> representing the alpha channel value of the color, where the number 0 corresponds to 0% (fully transparent) and 1 corresponds to 100% (fully opaque). Additionally, the keyword none can be used to explicitly specify no alpha channel. If the A channel value is not explicitly specified, it defaults to 100%. If included, the value is preceded by a slash (/).
A <number>, a <percentage>, or the keyword none (equivalent to 0% in this case). This value is a measure of the color's chroma (roughly representing the "amount of color"). Its minimum useful value is 0, while the maximum is theoretically unbounded (but in practice does not exceed 0.5). In this case, 0% is 0 and 100% is the number 0.4.
A <number>, an <angle>, or the keyword none (equivalent to 0deg in this case) representing the color's <hue> angle.
A <number> between 0 and 1, a <percentage> between 0% and 100%, or the keyword none (equivalent to 0% in this case). In this case, the number 0 corresponds to 0% (black) and the number 1 corresponds to 100% (white). This value specifies the color's perceived lightness, or "brightness".
opacity(factor)
A value of 0% makes the element invisible.
polygon([<fill-rule>,]? [<shape-arg> <shape-arg>]#)
The filling rule used to determine the interior of the polygon. Possible values are nonzero and evenodd. Defaults to nonzero if omitted.
Each pair defines a horizontal and vertical coordinate of a vertex of the polygon.
radial-gradient([ [ <shape> || <size> ] [ at <position> ]?, | at <position>, ]? <color-stop> [, <color-stop> ]+)
Determines the center of the gradient. Uses the same syntax as the 'background-position' property. Default value is 'center'
Can be either 'circle' or 'ellipse'. Default is 'ellipse'.
Determines the size of the gradient. Values can be lengths and percentages (if the gradient is an ellipse, two values define width and height) or keywords, which are 'closest-side', 'closest-corner', 'farthest-side' and 'farthest-corner'.
Defines the colors of the gradient. Syntax is "<color> [ <percentage> | <length>]?".
repeat([ <integer> , [ <line-names>? <track-size> ]+ <line-names>? ] | [ [ auto-fill | auto-fit ] , [ <line-names>? <fixed-size> ]+ <line-names>? ] | [ <integer> , [ <line-names>? <fixed-size> ]+ <line-names>? ])
repeating-linear-gradient([ [ <angle> | to <side-or-corner> ] ,]? <color-stop> [, <color-stop>]+)
The angle of direction for the gradient.
The direction of the gradient, using keywords. Syntax is [ left | right ] || [ top | bottom ].
Defines the colors of the gradient. Syntax is "<color> [ <percentage> | <length>]?".
repeating-radial-gradient([ [ <shape> || <size> ] [ at <position> ]# ]? <color-stop> [, <color-stop> ]+)
Determines the center of the gradient. Uses the same syntax as the 'background-position' property. Default value is 'center'
Can be either 'circle' or 'ellipse'. Default is 'ellipse'.
Determines the size of the gradient. Values can be lengths and percentages (if the gradient is an ellipse, two values define width and height) or keywords, which are 'closest-side', 'closest-corner', 'farthest-side' and 'farthest-corner'.
Defines the colors of the gradient. Syntax is "<color> [ <percentage> | <length>]?".
rgb(red, green, blue[, alpha]?)
Red color component. Number between 0 and 255 or percentage.
Green color component. Number between 0 and 255 or percentage.
Blue color component. Number between 0 and 255 or percentage.
Alpha color component. Number between 0 and 1 or percentage.
rgba(red, green, blue[, alpha]?)
Red color component. Number between 0 and 255 or percentage.
Green color component. Number between 0 and 255 or percentage.
Blue color component. Number between 0 and 255 or percentage.
Alpha color component. Number between 0 and 1 or percentage.
running(custom-ident)
Defines the name of the running element, which then is referenced by the element() function.
saturate(factor)
A value of 0 completely desaturates the colors, 1 or 100% leaves them unchanged and greater values increase the saturation.
-ro-separation([[ <string> | <identifier> ] <tint>?, <color>])
The name of the pantone.
The tint of the color. Number between 0 and 1 or percentage. Defaults to 1.
A CMYK or RGB version of the color for the case that the pantone is unknown (e.g. the color on a screen).
sepia(factor)
0 or 0% leaves the element's colors unchanged.
-ro-sidenote([ <side> || closest ]?)
One of the following values: left, right, start, end, inside, outside, recto or verso. Start and end are based on the sidenote's container text direction. Inside and outside are based on whether the sidenote's page is left or right. Recto and verso are based on the document's text direction, with recto being right in a left-to-right document. If omitted, the side is resolved to 'recto'.
If the sidenote element originates in a multi-column element, it is moved to the left side for all left columns or to the right for all right columns. If it is in the middle column, the side determined via the <side> argument. Has no effect if the sidenote element is not inside a multi-column context. Note that this argument is separated with a space from <side>, not a comma.
string(<custom-ident> [ , [ first | start | last | first-except] ]?)
The name of the named string which is set via the property string-set.
If there are multiple assignments on a page, this keyword specifies which one should be used.
target-counter([ <string> | <url> ] , <custom-ident> [ , <counter-style> ]?)
The url of the target.
Name of the counter.
Used to format the result, see the property 'list-style-type' for more information on the keywords.
-ro-target-counter-offset([ <string> | <url> ] , <custom-ident>, <integer> [ , <counter-style> ]?)
The url of the target.
Name of the counter.
The offset by which the counter value is modified.
Used to format the result, see the property 'list-style-type' for more information on the keywords. Default is 'decimal'.
target-counters([ <string> | <url> ] , <custom-ident> , <string> [ , <counter-style> ]?)
target-text([ <string> | <url> ] [ , [ content | before | after | first-letter] ]?)
The element whose content should be retrieved.
Specifies what content is retrieved, using the same values as the 'string-set' property.
var(<custom-property-name> [ , <declaration-value> ]?)
The variable name
The fallback value, which is used in case the variable is invalid in the used context
:-ro-nth(An+B | even | odd)
Describes on which page numbers this selector should match. A and B are integers, while n is the non-negative variable (counting from 1 to the total number of pages). The selector matches if the number of previous pages is a solution of the expression.
:is(s)
A single or a list of selectors.
:lang(languagecode)
The language code to match, e.g. "de", "en", "it", etc.
:-ro-matches(s)
The selector to match.
:not(s)
The single selector or selector list to match.
:nth-child(An+B | even | odd)
:nth-last-child(An+B | even | odd)
:nth-last-of-type(An+B | even | odd)
:nth-of-type(An+B | even | odd)
:where(s)
A single or a list of selectors.
@charset <string>;
@counter-style <identifier> { ... }
@font-face { ... }
@footnote {...}
@import <url> <media-type>#?;
@media <media-condition> || [[only | not]? <media-type>? [and <media-condition>]?]
@namespace <identifier> <url>
@page <identifier>? [:first | :blank | :left | :right | :recto | :verso | :-ro-last | :-ro-nth(An+B [of name]?)]? { ... }
@-ro-preferences {...}
@-ro-sidenote [:left | :right | :verso | :recto | :inside | :outside]?
@supports <supports-condition> { ... }
@top-left { ... }
xx-small | x-small | small | medium | large | x-large | xx-large
part | art | sect | div | blockquote | caption | toc | toci | index | nonstruct | private | h | h1 | h2 | h3 | h4 | h5 | h6 | p | l | li | lbl | lbody | table | tr | th | td | thead | tbody | tfoot | span | quote | note | reference | bibentry | code | link | annot | ruby | rb | rt | rp | warichu | wt | wp | figure | formula | form
simple | simple-block | simple-block-strict | simple-inline | table-struct | list-struct
<pdf-standard-structure-type> | <pdf-tag-kind> | artifact | none | <string>
larger | smaller
The following table lists the JavaScript libraries and frameworks tested with PDFreactor. These tests were done using GraalJS as JavaScript engine. Please refer to the JavaScript chapter for more information. Other libraries and frameworks or other minor versions of the listed ones may still be functional, they are merely untested. Frameworks with only a check mark passed all of our internal tests, while the others are subject to known limitations. Please refer to the respective column for further details.
Library | Successfully tested Versions | Support | Known Limitations |
amCharts | 5.10.5, 3.21.15 |
||
Angular | 18.2.5, 17.3.12, 16.2.12 |
||
Angular.js | 1.8.3 | ||
bignumber.js | 9.1.2 | ||
Bootstrap | 5.3.3 | Toogle buttons are overlayed with a checkmark, to remove them, add the following style:
|
|
Chart.js | 2.9.4 | When an array with colors is passed instead of a string where only one color is expected, this may cause a fallback to gray. In most cases, browsers use the first value instead. | |
Flotr2 | 0.1.0 | ||
Handlebars | 4.7.8 | ||
Highcharts | 11.4.8 |
|
|
Highcharts | 10.3.3 | ||
jQuery | 3.7.1 | ||
JSZip | 3.10.1 | ||
Leaflet | 1.9.4 | ||
Less | 4.2.0, 3.13.1, 2.7.3 |
||
Lodash | 4.17.21 | ||
MathJax | 2.7.9 |
|
|
Modernizr | 3.13.1 | ||
MooTools | 1.6.0 | ||
Plotly.js | 2.35.2 | Shadows applied on text are not rendered, which may result in labels being hard to read. | |
Prototype | 1.7.3 | ||
Raphaël | 2.3.0 | ||
React | 18.3.1, 17.0.2 |
||
RequireJS | 2.3.6 | ||
Underscore.js | 1.13.7 | ||
Vue.js | 2.7.16 |