Flexible processing with dynamic variables

Sometimes it is necessary to check against different values each time a check or fixup is carried out. As pdfToolbox offers dynamic checks and fixups – through the use of dynamic variables – there is no need to create separate checks and fixups each time the target values change. Instead the target value or values can be entered each time the check, fixup or profile is executed.

This tutorial explains the use of dynamic variables for setting up a check. In addition, the same dynamic variable mechanism can be used for fixups and profiles. Profiles may contain several checks or fixups making use of dynamic variables. As variables are identified by their internal name, they can be re-used across a single check or fixup. For any given variable name, pdfToolbox will only ask once per execution for the value to be used.

Open the pdfToolbox "Checks" panel

Select the menu entry "Checks" under the "Tools" menu to open the "Checks" panel.

Open "Create New pdfToolbox Check..." dialog

In the upper right of the pdfToolbox "Checks" panel is the "Tools" button – click on it and then select "Create New pdfToolbox 4 Check..."

Create new check

  1. Once the "New Check" dialog has opened, enter a self-explanatory name for the check to be created.
  2. As we intend to create a dynamic check for minimal required image resolution, enter "resolution" in the search field in the upper right, so we can more easily find the right property in the list of properties (did you know that pdfToolbox comes with over 1000 different properties to check for?)
  3.  For the purpose of this tutorial, we will choose "Image resolution" by clicking on the small yellow "Add..." button.
  4. After having clicked on "Add...", the dialog will be populated with the necessary parameters.

Create new check

  1. Finally we are about to enter the threshold value in the "Number" field. Nevertheless, as we want to be able to specify the actual threshold value at runtime – when executing the check – we will not simply enter a numerical value here. Instead, click on the "orange with a black stroke" button to the right of the "Number:" value field.

The "dynamic variable" setup dialog

See next step for instructions about how to fill out the "Variables" dialog.

Contents of the "Variables" dialog

In the "Variables" dialog, enter the following values:

  1.  A name for the variable; no spaces are allowed inside the name, and while it is possible to use lower and upper case as well as numbers, it is recommended to always use short uppercase names, preferably with underscores to make the variable name more easily readable; we use "IMAGE_RES" for our example.
  2. The text to be displayed at runtime, when the user is asked to enter the actual value. The text should be short and explain the purpose of the value to be entered. For this example, "Enter min. resolution" is used.
  3. Finally, a proposed value must be entered. This will typically be a value that makes sense as a default value. In this example, a value of "300" is entered.
  4. After filling out the three fields, confirm the entries by clicking "OK" and closing the dialog.

Placeholder for "dynamic variable"

Upon closing the "Variable" dialog, the variable definition will be inserted in the "Number:" field as a placeholder token.

The same placeholder token can be used in more than one place – for example in the name field. Even in cases where a variable occurs more than once in a check (or fixup or profile), the user has to enter it only once when executing it.

By putting the same dynamic variable inside the name for the check will retrieve the value from the placeholder token for displaying the name (either the default value for display in the list of checks, or in the results information after running a check – in that case it will be the value entered by the user).

Copy and paste the dynamic variable

In order to reuse the variable in a different field, just select and copy it and paste it at the end of the name field – in this example "Image res is below" will then be displayed as "Image res is below 300" (or if you add " ppi" after the placeholder token, it will say "Image res below 300 ppi").

Once done, click "OK" and close the dialog, saving the new check.

New "dynamic check" in list of checks

  1. After having created the new "dynamic check", it will be listed in the pdfToolbox "Checks" panel.
  2. The three dots above the check icon for the entry are an indicator that this check is a dynamic check, rather than a static check with all values predefined.
  3. Click "Analyze" to apply the newly created dynamic check.

Running the "dynamic check"...

Once having clicked on the "Analyze" button, the check will be initiated, first asking the user to enter a value for the dynamic variable.

  1. The display string "Enter min. resolution" is taken from the setup for the dynamic variable. 
  2. The initial value "300" in the dialog is the default value configured for the dynamic variable. The user can change it to the value to be used for this execution of the check (when executing the check the next time, the initial value will revert to the default value).

Entering a value of "150"

Executing the dynamic check with a value of "150"

Checking for an image resolution below 150 ppi identifies 749 images in sample PDF

As can be seen, it is very easy to adjust the check each time as needed.

Creating a dynamic check with more than one dynamic variable

The use of dynamic variables is not limited to just one variable in a check (or fixup or profile). In essence, variables can be used for virtually any text edit field in dialogs that let you configure checks, fixups or profiles.

Create new check with lower and upper limit for image resolution

We intend to be able to have a check that finds images whose resolution is within a certain range. As a consequence, we need two parts for the check, one for the lower bound, the other one for the upper bound.

  1. Just click twice on the "Add..." button for the "Image resolution" property.

Two part check

Prepare the two parts of the check such that one is set to search for values "greater than" the threshold value (1), and the other one for values "less than" (2). Then click on the "dynamic variable button" next to the two "Number:" fields (3  and  4).

Configure the dynamic variable for the smallest acceptable resolution

Configure the dynamic variable for the highest acceptable resolution

Use two placeholder tokens for name of dynamic check

By copying and pasting the respective placeholder tokens, you can change the string "Image res is between ... and ..." into a more intuitive "Image res is between 72 and 300", where the numbers 72 and 300 are taken from the dynamic variable setup, and where different numbers may be displayed in the results after running the check, if the user entered different minimum and maximum values.

Simply click "Continue" ...

Under certain circumstances, it may happen that a warning is shown, claiming that two properties contradict each other. Just click "Continue" to proceed.

New check listed in "Checks" panel

Once the creation of the new check is completed, it will show up in the "Checks" panel (1). Click on "Analyze" to run the new check on the current PDF document (2).

Enter lower and upper bounds for dynamic image resolution check

In the example, images will be detected which have a resolution between 70 ppi and 150 ppi.

Results from executing the dynamic check with lower and upper bounds

The dynamic check will find images between 70 ppi and 150 ppi but ignore images below 70 ppi or above 150 ppi.