JavaScript controlled checks - principles

Arbitrary JavaScript controlled Checks is a condition that can be added to any check. The quickest way to find it, is to open the check editor (for an existing or a new check), and type "javascript" in the search box.

It is important to note that this is a condition, not a check. This means that the 'Arbitrary JavaScript controlled Checks' condition has to be added to a check, and can be combined with other conditions.

The condition

When the condition is added to a check, it appears as follows:

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;
Click to copy

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). Two possibilities exist.

Creating conditions

In this case, the JavaScript object must contain a "conditions" property. This is an array of individual conditions.

const configuration = {
	conditions: [{
		"operator" : "less_than",
		"property" : "CSTEXT::Textsize",
		"tolerance" : 0.0,
		"value" : 10.0
	}]
};

configuraration;
Click to copy

The example above has a single condition, that checks for text size smaller than 10 points (with no tolerance). In this setup, pdfToolbox adds the condition defined in JavaScript to any other conditions this check may have. All other properties of the check that contains this condition are set by the normal check user interface; the JavaScript code simply add one or more conditions to the check.

Creating checks

In this case, the JavaScript objects must contain a "checks" property. This is an array with one or more check objects.

const configuration = {
   "checks" : [
      {
         "comment" : "",
         "condition_logic" : "and",
         "conditions" : [
            {
               "operator" : "less_than",
               "property" : "CSTEXT::Textsize",
               "tolerance" : 0.0,
               "value" : 10.0
            }
         ],
         "custom_id" : "",
         "invert" : false,
         "name" : "Text is smaller than 10 pt",
         "report_no_match" : "",
         "scope" : {
            "annotations" : false,
            "current_file" : true,
            "embedded_files" : false,
            "form_fields" : false,
            "output_intent" : "document",
            "page_box" : "none",
            "page_contents" : true,
            "processing_steps" : "ps_and_non_ps",
            "soft_masks" : false
         },
         "severity" : "error"
      }
   ]};

configuraration;
Click to copy

The example above defines a single check, that checks for text size smaller than 10 points (with no tolerance). However, in this setup, pdfToolbox creates a completely new check, and you can now override any parameter from the check user interface. The JavaScript can for example control what is going to end up in a preflight report as error message, by dynamically calculating the "name" property for the created check.

The advantage of this approach is that you are not limited to creating one check, but you can create an arbitrary number of checks, for example based on incoming variables.

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.