Script variables can be used wherever Simple variables can be used:
- In Checks or Fixups for text input fields, pop ups, checkboxes
- Severities of checks
- On/Off variables for Checks and Fixups
It in addition is possible to use Script variables (but not Simple variables):
- in a Profile as Profile script
- as a Process Plan step
In all places where Simple or Script variables can be used, the variable editor allows you to switch between both by means of a radio button. After a variable has been saved as Simple variable is is possible at any time to convert it into a Script variable here. However, it is not possible to convert a Script variable into a Simple variable. The reason is that this could potentially lead to problems when the same variable would be used in a place where only a Script variable is allowed.
Assigning a variable to a pdfToolbox Desktop control
Wherever you see the variable icon in pdfToolbox Desktop you can click on it in order to assign a variable from a list of all variable keys that are defined in the current Library to the respective control.
You can create a new variable (either as Simple or as Script variable) and assign it; or you open the variable editor in order to modify a variable that has already been assigned.
In order to un-assign a variable from a control you simply have to remove it from a text input field, to pick any other value in a pop up or to check/uncheck a checkbox.
In pdfToolbox versions earlier than version 9 it was possible to copy a variable out of a pdfToolbox Desktop control and insert it into another control in order to assign it to both controls. This is not possible in pdfToolbox 9. You have to select the variable key from the variable pop up in the second or any further control.
From pdfToolbox 9 on it is no more possible to make two variable occurrences using the same value simply by using the same variable name ("key"). Variables are only then the same if any additional occurrence is selected from the variable pop up in pdfToolbox Desktop. Otherwise two variables using the same key would be present which would at least be confusing when evaluated.
But: It would be difficult to resolve such conflicts when a Profile is imported as kfpx file, if the imported Profile uses the same variable key as a variable that is already present in the current Library. Therefore in such cases internally a variable merge process takes place that merges all variables that are defined in the very same way (key, default value and label) into a single variable.
Defining a variable in a script
If you want to define a variable in a script that is not used in any pdfToolbox Desktop control you may do so by writing at the top of your script:
myvar will then be created and show up in the Ask at Runtime dialogue or in --listvariables on command line. If you also want to set a default value and a display name (label) you can write:
app.requires("myvar",100,"Input a value for myvar")
Setting the value for a Script variable in it's own script
Setting the value for another Script variable with app.vars
app.vars.myvar = "pdfToolbox";
localvar = app.vars.myvar;
are valid statements. The first statement would create the variable "myvar" if not already present in app.vars. You may e.g. use app.vars to set a value for a variable on Profile level, which is then used in a Fixup in the Profile.
In order to set a value for a Simple variable you can use app.vars.<variable key>. A list of all variables that are present in the current Library can be displayed in the Script editor by using [<command>-2].
Using variables that are defined elsewhere
When retrieving variable values from app.vars it is important to know that all variables are stored there as strings. With simple value types you will most probably not even notice this, because a string is automatically converted if necessary and possible, e.g. into a number. However, if you are working with more complex variable types like with arrays or objects there will obviously be differences and you might have to work around this limitation.
In complex profiles - actually when a Script variable is used in another Script variable - app.requires("<variable key>") has to be defined at the top of the referencing Script, in addition to the actual reference with app.vars. This is required in order to make sure that the referenced variable is evaluated before the referencing variable is calculated. So, it is good practice to at the top of each Script, list all variables which are not defined in the Script itself in app.requires entries.
Profile level scripts versus Check/Fixup level scripts
Example: Downsample images in pdfToolbox usually requires to set up three fixups: for color images, grayscale images and for bitmap images. Each of the fixups has two input fields that you may want to make variable: The destination resolution and the minimum resolution for an image to be downsampled. Assume that you want to downsample color and grayscale images to the same resolution. Images should be downsampled if the original image resolution is 1.5 times as high as the destination resolution. Destination resolution for bitmap images should be 3 times as high as for color images, with the same relative minimum resolution (effectively 4.5 times color images' minimum resolution). You may now either make the destination resolution for color images a Simple variable, e.g. "dest_col_res" and make any of the other 5 variables a Script variable that uses dest_col_res and calculates the actual value. Or you set up a Profile level script, do all the calculations there and put the results into a bunch of Simple variables that you assign to each of the 6 variable input fields. (You will have to use app.vars in order to use variables throughout the Profile and in the second case you would use app.requires to define a variable for the destination image resolution in the Profile script.)
Each of the two approaches has advantages:
- If you put the intelligence into Fixups and Checks it is easier to make it possible to use them as Single Fixups or Checks, independent from the Profile.
- If you put the intelligence into the Profile it is usually easier to see what a profile is actually doing and - even more important - to maintain it in the future.
As a result and a rule of thumb it can be said, that it usually makes sense to put as much intelligence into the Profile level script. The more complex a Profile is, the more important is it to follow this approach.
The Script editor: User interface elements: Help
When the variable editor is switched into Script "mode", you can find help with the info button on the upper right side of the Script input field. You will find more information if you click into the Script input field first. This gives you access to
- a general help text (this text) [<command>-0],
- a list of all variables that are present in the current Library [<command>-2]
- useful code snippets [<command>-3].
The Script editor: User interface elements: Value type
Above of the info button you see the value type of the pdfToolbox control to which the variable is currently assigned. This information is useful to know what type of result is expected from your script.
The Script editor: User interface elements: Show evaluation results
A button at the right hand side indicates whether the result of the script works in the current pdfToolbox control. If the result is "pdfToolbox" and you are using the variable for a text input field you will see a green checkmark. However, if the variable is used for an integer number field you will see a red error cross. When you click on it you will read: ""pdfToolbox" cannot be converted to integer".
Inspecting the variable structure in the Ask at Runtime dialogue in pdfToolbox Desktop: Activating the "debug view"
When you run a Process Plan, Profile, Check or Fixup in pdfToolbox Desktop that uses variables you will see the "Ask at Runtime" that allows for updating variable values. A checkbox at the bottom of the dialogue allows the user to "Inspect variables".
Inspecting the variable structure in the Ask at Runtime dialogue in pdfToolbox Desktop: The "debug view"
If activated all calculated variables are displayed, not only those ones that allow for user input. A "Script" indicator shows values that cannot be modified in this dialogue because they are already calculated in the scripts. A button behind the Script variable fields indicates whether there is a type conflict, e.g. if the variable is used for a number field but the value is a string that cannot be converted to a number. In that case you will see a red cross. You may click on any of those red cross buttons in order to see details for the problem.
The Ask at Runtime dialogue will only appear if a Profile/Check/Fixup has at least one variable that does not already have a value. If you want to enable the debug view in a Profile/Check/Fixup in which all variables are set by means of scripts, you will have to add at least one additional variable, e.g. a Simple variable for that purpose.
Inspecting the variable structure in the Ask at Runtime dialogue in pdfToolbox Desktop: The "debug view" info button
Next to each variable you will see an info button. Clicking on this button allows for accessing information that is useful for debugging purposes. A list of all variables that are defined in the current context is displayed. (The content of the info window is actually the same for each of the info buttons, the only difference is that the control for the respective variable is opened by default.) Each of these variables is followed by the result that has been calculated for the respective variable. If you open the triangle for a variable you see an entry "Variables" that shows details about how that variable has been defined. Below are all contexts listed in which the respective variable is used.