Arbitrary JavaScript controlled Fixups

Why this new type of Fixup?

Sometimes you need to do calculations or you want to use lots of variables while configuring one or more Fixups in pdfToolbox. The "Arbitrary JavaScript controlled Fixups" provides a powerful alternative to using regular Fixups in this case.

The Fixup works by providing you with two JavaScript code areas where you can build a configuration for one or more regular Fixups. pdfToolbox then builds the Fixups from the JavaScript objects you provide, and executes them as part of a Profile or Process plan. You shouldn't see this as an easy replacement of standard Fixups, but as an alternative when using regular Fixups would provide very difficult; a good example would be doing color replacement without knowing ahead of time how many colors you want to replace.

Setting up the Fixup

The Fixup contains two JavaScript areas in order to setup it up:

  1. The main JavaScript area. Here, you should create a configuration object and pass it back to pdfToolbox.
  2. The resource area. Here you must list any resources your JavaScript created Fixup requires so they can be properly managed by pdfToolbox.
  3. Info button which provides help on what to enter in the configuration area. The different possibilities are explained below. 

Some property names have been changed in pdfToolbox 13. The old values are still accepted during execution, but if inserted by one of the menu items (“Insert configured fixup…” ec.pp.) the new property names are used. If both properties are present the new property name takes precedence.

pdfToolbox 12 pdfToolbox 13
displayName
 name
displayComment
 comment
customID
 custom_id

In pdfToolbox 13, additional Fixup settings have been added to the JSON serialisation:

  "scope" : {
     "current_file" : true,
     "embedded_files" : false
  }
Click to copy

The main JavaScript area

pdfToolbox expects you to return a JavaScript object containing one or more Fixups. The standard form could look something like this:

// The object containing all of the Fixup definitions
const configuration = {
	
	// A fixup
	flip_pages: {
		config: {
			// fixup specific setup
		}
		displayName: "The name to be used in the report",
		displayComment: "The comment sometimes also shown in reports"
	},

	// Optionally a second, third... fixup
	
};

// This line makes sure it is passed back to pdfToolbox. Do not use "return" here.
configuration;
Click to copy

Some remarks about the code above:

  • "flip_pages" is the identifier for the Fixup we want to use.
  • "config" is where you add the properties for the specific Fixup you are setting up. As each Fixup is different, this section typically will be different for each Fixup.
  • "displayName" and "displayComment" are optional, but allow you to build the name and comment used in preflight reports when this Fixup is run.

So how do you find out what to put in the config area? Click on the blue "i" button and you have three possibilities:

  1. Open list of all base Fixups
    This opens documentation on the setup required for all Fixups. Read more in this article.
  2. Insert base Fixup
    This opens the "create Fixup" window. Now you can create a new Fixup with all specific properties. After you click the "Ok" button, the Fixup is inserted into the JavaScript editor.
  3. Insert configured Fixup
    This shows you a list of all Fixups of the current library and lets you choose one. pdfToolbox then adds the Fixup with all defined properties into the JavaScript editor.

Things to look out for

While configuring this Fixup is relatively straightforward, there are still some things to be cautious about...

  • pdfToolbox expects JavaScript code, not a JSON object. You'll have to write some JavaScript statements that produce a "result". This result should then contain the setup for the Fixup. You can accomplish this in different ways, but pdfToolbox has no preference - your code simply has to produce a result.
  • You can create multiple Fixups in this JavaScript structure. You can't however have the same type of Fixup twice. If I inserted a "flip_pages" Fixup, I can't add another of those to my JavaScript structure. While there are way to cheat pdfToolbox by inserting something like this into your JavaScript, it's not going to work when you execute the Fixup.
  • Some Fixups internally allow multiple configurations to be setup (using the little "+" and "-" buttons in the user interface when setting up the Fixup). Such Fixups can be configured as well, and in this case the "config" property in your JavaScript structure will be an array. If you're unclear how to do this, create an example Fixup and then use "Insert configured Fixup" to have pdfToolbox show you the way.

Example

A simple example to mirror pages horizontally is included here and can be imported into your library. However, with the "Insert configured Fixup" option it's easy to create your own examples. All that's left afterwards is to adjust them to your taste!

04__01__Flip_pages_horizontally.kfpx