JavaScript controlled checks - how to build

When using the "Arbitrary JavaScript controlled Checks" feature, the most difficult part is to find the correct syntax for the conditions or checks you want pdfToolbox to create for you. Luckily there are a number of tools you can use to make your life easier. This article describes all of them so you can effectively use them. To follow along, create a new check, search for the "Arbitrary JavaScript controlled Checks" condition and add it to your check. You should end up with an empty JavaScript editor.

The tools we're looking for are available from the "i" button in the right hand corner of the JavaScript editor. We're going to be looking at three of these menu items in this article.

While we're not going to focus here on the bottom three menu items, these are identical to what is available for regular JavaScript variables. There's a separate help item that talks about this functionality: article.

Insert base Check...

To use this functionality, start with the following code in the JavaScript editor:

const configuration = {

	checks: [

		<place cursor here>

	]
};

configuraration;
Click to copy

The code creates the configuration code pdfToolbox needs to create "check" objects. The "checks" property is an array that should contain the JavaScript description of the checks you want to create. Put the text cursor at the spot marked with "<place cursor here>" in the example code. (the angular brackets <> and the text in between can of course be deleted from the code; they're just there so you would know where to place your cursor for the next step).

Now click the "Insert base Check..." menu item from the "i" button.

This opens up a regular preflight check editor window. Configure this check exactly how you want it. For this example, configure a simple check as follows:

Add as many conditions as you want, and configure also the information on the left hand side of the editor (name, description, custom ID....). When the check looks exactly as you want it, click the "OK" button. The JavaScript code that represents the preflight check you just configured, is now inserted into the JavaScript editor, at the location of the text cursor.

You can now format this inserted code to fit the rest of your code, and adjust it to add any additional logic you need.

Insert configured Check...

An even better way to get started, is to use "Insert configured Check". Using this is quite similar to using a base check, with the exception that you build the check you want to insert first. Follow these steps:

  1. Create a new check.
  2. Configure it exactly how you want. Make sure it has correctly-configured conditions, a good name and description, and so on.
  3. Save the check and test it on some documents to make sure it behaves exactly as you want.
  4. Create a new check.
  5. Insert the "Arbitrary JavaScript controlled Checks" condition.
  6. In the JavaScript code editor, insert the same base code as used for "Insert base check".
  7. Click the "i" button, and then "Insert configured Check...".
  8. A window opens that lets you select the check you had previously configured and tested. Select it and click OK.

The JavaScript code that represents the preflight check you just configured, is now inserted into the JavaScript editor, at the location of the text cursor. You can now format this inserted code to fit the rest of your code, and adjust it to add any additional logic you need.

The advantage of this method, is that you can prepare your 'template' check and test it properly before generating the JavaScript code for it.

Open list of all base Checks

One additional problem is how to know what values each property supports. Perhaps I'm using a condition in a check on text size, and I want to use different operators (for "smaller than", "equal to", etc...) based on the value of a variable. How is it possible to know how these operators are represented in the JavaScript code?

To solve this, use the 'i' button again, and click on the "Open list of all base Checks" menu item. This opens a (very long) page in your favorite web browser. The page contains a list of all checks pdfToolbox supports, and shows its properties. For each property, you can see what the possible values are. So, let's say the JavaScript code now contains:

         "conditions" : [
            {
               "operator" : "less_than",
               "property" : "CSTEXT::Textsize",
               "tolerance" : 0.0,
               "value" : 10.0
            }
         ],
Click to copy

 To know what the text strings (like "less_than") are for the other operators, follow these steps:

  1. Click on the 'i' button, and then on the "Open list of all base Checks".
  2. In the browser page that opens, do a text search for the string "CSTEXT::Textsize".
  3. Look at the list of possible operators supported for this property and select the one you want.
    Caution: the information you are looking for may be just after, or just before the line you find by doing the search.