JavaScript controlled fixups - principles
Arbitrary JavaScript controlled Fixups is a type of fixup. To use it, create a new Fixup and type "javascript" in the search box.
As soon as you select the fixup type in the list above, the JavaScript editor appears at the bottom. Just as for Arbitrary JavaScript controlled Checks, there is a "Script" and a "Resources" area.
JavaScript
In order to use it, you need to write JavaScript. The result of this JavaScript needs to be a JavaScript object that contains specific properties. A common way to start would be:
const configuration = {
...
};
configuraration;The first three lines define an object called "configuration". The last line makes sure that the result of the whole JavaScript is this object. pdfToolbox picks up this object and uses what it finds inside (if it follows the rules). The object can of course not be empty as in our example; you need to define properties in it (they would replace the "..." in the example).
Specifying fixups to create
For the "Arbitrary JavaScript controlled Fixups" fixup, the object passed to pdfToolbox can specify different fixups that need to be created. Each of these fixups must be inserted into the configuration object using a specific property; identifying the fixup to pdfToolbox.
const configuration = {
"rotate_pages" : {
"comment" : "",
"config" : [
{
"params" : {
"apply_to" : "always",
"rotate" : "180_clockwise"
}
}
],
"custom_id" : "",
"name" : "Rotate pages 180 degrees",
"scope" : {
"current_file" : true,
"embedded_files" : false,
"processing_steps" : "ps_and_non_ps"
}
}
};
configuration;The example above defines a single fixup. If you would look it up in the fixup editor, it would be listed as "Rotage pages". In the JavaScript object here, it is identified with the property name "rotate_pages". Each fixup has its own identification that can be used here.
The value of the "rotate_pages" property is an object that defines all properties for the fixup that pdfToolbox will run. All general properties such as the name (listed in the preflight report if the fixup is used), comment, scope, etc are listed at the top level of this object. The "config" object contains the specific configuration for this ("Rotate pages") fixup.
Important remarks
In some ways, the "Arbitrary JavaScript controlled Fixups" is simpler than the "Arbitrary JavaScript controlled Check". There are still a number of noteworthy remarks to be made.
Multiple fixups
The JavaScript allows you to create multiple fixups: the configuration object can contain multiple properties, where each property defines a different fixup. pdfToolbox creates all fixups you define in the configuration object and runs them.
However, you cannot define two instances of the same fixup. In the example above, I could not include two properties with the same "rotate_pages" name (this is actually not allowed by JavaScript). Luckily, I could still do something similar, as the Rotate Pages fixup supports multiple configurations.
Multiple configurations
Many fixups in pdfToolbox support multiple configurations. These fixups are easy to recognize in the fixup editor because they have additional buttons on the right hand side of the configuration area that allow deleting, adding, and duplicating a configuration.
This is also reflected in the JavaScript for these fixups.
"config" : [
{
"params" : {
"apply_to" : "always",
"rotate" : "180_clockwise"
}
}
],
The Rotate Pages example has a "config" property that is an array. This is because multiple configurations are available for this fixup. If that is not the case, the "config" property will be a simple object instead of an array of configuration objects.
Syntax issues
What is likely already clear from these simple examples, is that the JavaScript syntax used here, is quite complex. The question is how to know what the correct syntax is, and how you can create such JavaScript in the easiest way possible. The next article explains the help that is available to you to figure these things out.