module HexaPDF:: Type:: AcroForm:: JavaScriptActions
The JavaScriptActions
module implements JavaScript actions that can be specified for form fields, such as formatting or calculating a field’s value.
These JavaScript functions are not specified in the PDF specification but can be found in other reference materials (e.g. from Adobe).
- Formatting a field’s value
-
The main entry point is
apply_format
which applies the format to a value. Supported JavaScript actions are:-
AFNumber_Format
: Seeaf_number_format_action
andapply_af_number_format
-
AFPercent_Format
: Seeaf_percent_format_action
andapply_af_percent_format
-
- Calculating a field’s value
-
The main entry point is
calculate
which calculates a field’s value. Supported JavaScript actions are:-
AFSimple_Calculate
: Seeaf_simple_calculate_action
andrun_af_simple_calculate
-
Simplified
Field
Notation expressions: Seesimplified_field_notation_action
andrun_simplified_field_notation
-
See: PDF2.0 s12.6.4.17
See:
Constants
- AF_NUMBER_FORMAT_RE¶
Regular expression for matching the AFNumber_Format method.
- AF_PERCENT_FORMAT_RE¶
Regular expression for matching the AFPercent_Format method.
- AF_SIMPLE_CALCULATE¶
Mapping of AFSimple_Calculate function names to implementations.
- AF_SIMPLE_CALCULATE_RE¶
Regular expression for matching the AFSimple_Calculate function.
- AF_TIME_FORMAT_RE¶
Regular expression for matching the AFTime_Format method.
See:
apply_af_time_format
Public Instance Methods
Formats the numeric value according to the format string and separator style.
Returns the numeric value of the string, interpreting comma as point.
Returns the appropriate JavaScript action string for the AFNumber_Format function.
decimals
-
The number of decimal digits to use. Default 2.
separator_style
-
Specifies the character for the decimal and thousands separator, one of:
- :point
-
(Default) Use point as decimal separator and comma as thousands separator.
- :point_no_thousands
-
Use point as decimal separator and no thousands separator.
- :comma
-
Use comma as decimal separator and point as thousands separator.
- :comma_no_thousands
-
Use comma as decimal separator and no thousands separator.
negative_style
-
Specifies how negative numbers should be formatted, one of:
- :minus_black
-
(Default) Use minus before the number and black as color.
- :red
-
Just use red as color.
- :parens_black
-
Use parentheses around the number and black as color.
- :parens_red
-
Use parentheses around the number and red as color.
currency_string
-
Specifies the currency string that should be used. Default is the empty string.
prepend_currency
-
Specifies whether the currency string should be prepended (
true
, default) or appended (+false).
Returns the appropriate JavaScript action string for the AFPercent_Format function.
decimals
-
The number of decimal digits to use. Default 2.
separator_style
-
Specifies the character for the decimal and thousands separator, one of:
- :point
-
(Default) Use point as decimal separator and comma as thousands separator.
- :point_no_thousands
-
Use point as decimal separator and no thousands separator.
- :comma
-
Use comma as decimal separator and point as thousands separator.
- :comma_no_thousands
-
Use comma as decimal separator and no thousands separator.
Returns the appropriate JavaScript action string for the AFSimple_Calculate function.
type
-
The type of operation that should be used, one of:
- :sum
-
Sums the values of the given
fields
. - :average
-
Calculates the average value of the given
fields
. - :product
-
Multiplies the values of the given
fields
. - :min
-
Uses the minimum value of the given
fields
. - :max
-
Uses the maximum value of the given
fields
.
fields
-
An array of form field objects and/or full field names.
Returns the appropriate JavaScript action string for the AFTime_Format function.
format
-
Specifies the time format, one of:
- :hh_mm
-
(Default) Use 24h time format %H:%M (e.g. 15:25)
- :hh12_mm
-
(Default) Use 12h time format %l:%M %p (e.g. 3:25 PM)
- :hh_mm_ss
-
Use 24h time format with seconds %H:%M:%S (e.g. 15:25:37)
- :hh12_mm_ss
-
Use 24h time format with seconds %l:%M:%S %p (e.g. 3:25:37 PM)
See: apply_af_time_format
Implements the JavaScript AFNumber_Format function and returns the formatted field value.
The argument value
has to be the field’s value (a String) and action_string
has to be the JavaScript action string.
The AFNumber_Format function assumes that the text field’s value contains a number (as a string) and formats it according to the instructions.
It has the form AFNumber_Format(no_of_decimals, separator_style, negative_style, currency_style, currency_string, prepend_currency)
where the arguments have the following meaning:
no_of_decimals
-
The number of decimal places after the decimal point, e.g. for 3 it would result in 123.456.
separator_style
-
Defines which decimal separator and whether a thousands separator should be used.
Possible values are:
0
-
Comma for thousands separator, point for decimal separator: 12,345.67
1
-
No thousands separator, point for decimal separator: 12345.67
2
-
Point for thousands separator, comma for decimal separator: 12.345,67
3
-
No thousands separator, comma for decimal separator: 12345,67
negative_style
-
Defines how negative numbers should be formatted.
Possible values are:
0
-
With minus and in color black: -12,345.67
1
-
Just in color red: 12,345.67
2
-
With parentheses and in color black: (12,345.67)
3
-
With parentheses and in color red: (12,345.67)
currency_style
-
This argument is not used, should be 0.
currency_string
-
A string with the currency symbol, e.g. € or $.
prepend_currency
-
A boolean defining whether the currency string should be prepended (
true
) or appended (false
).
Implements the JavaScript AFPercent_Format function and returns the formatted field value.
The argument value
has to be the field’s value (a String) and action_string
has to be the JavaScript action string.
The AFPercent_Format function assumes that the text field’s value contains a number (as a string) and formats it according to the instructions.
It has the form AFPercent_Format(no_of_decimals, separator_style)
where the arguments have the following meaning:
no_of_decimals
-
The number of decimal places after the decimal point, e.g. for 3 it would result in 123.456.
separator_style
-
Defines which decimal separator and whether a thousands separator should be used.
Possible values are:
0
-
Comma for thousands separator, point for decimal separator: 12,345.67
1
-
No thousands separator, point for decimal separator: 12345.67
2
-
Point for thousands separator, comma for decimal separator: 12.345,67
3
-
No thousands separator, comma for decimal separator: 12345,67
Implements the JavaScript AFTime_Format function and returns the formatted field value.
The argument value
has to be the field’s value (a String) and action_string
has to be the JavaScript action string.
The AFTime_Format function assumes that the text field’s value contains a valid time string (for HexaPDF
that is anything Time.parse can work with) and formats it according to the instructions.
It has the form AFTime_Format(time_format)
where the argument has the following meaning:
time_format
-
Defines the time format which should be applied.
Possible values are:
0
-
Use 24h time format, e.g. 15:25
1
-
Use 12h time format, e.g. 3:25 PM
2
-
Use 24h time format with seconds, e.g. 15:25:37
3
-
Use 12h time format with seconds, e.g. 3:25:37 PM
Handles JavaScript field format actions for single-line text fields.
The argument value
is the value that should be formatted and format_action
is the PDF format action object that should be applied. The latter may be nil
if no associated format action is available.
Returns [value, nil_or_text_color] where value is the new, potentially changed field value and the second argument is either nil
(no change in color) or the color that should be used for the text value.
Handles JavaScript calculate actions for single-line text fields.
The argument form
is the main Form
instance of the document (needed for accessing the fields for the calculation) and calculation_action
is the PDF calculate action object that should be applied.
Returns the calculated value as string if the calculation was succcessful or nil
otherwise.
A calculation may not be successful if
-
HexaPDF
doesn’t support the specific calculate action (e.g. because it contains general JavaScript instructions), or if -
there was an error during the calculation (e.g. because a field could not be resolved).
Implements the JavaScript AFSimple_Calculate function and returns the calculated value.
The argument form
has to be the document’s main AcroForm
object and action_string
has to be the JavaScript action string.
The AFSimple_Calculate function applies one of several predefined functions to the values of the given fields. The values of those fields need to be strings representing numbers.
It has the form AFSimple_Calculate(function, fields))
where the arguments have the following meaning:
function
-
The name of the calculation function that should be applied to the values.
Possible values are:
SUM
-
Calculate the sum of the given field values.
AVG
-
Calculate the average of the given field values.
PRD
-
Calculate the product of the given field values.
MIN
-
Calculate the minimum of the given field values.
MAX
-
Calculate the maximum of the given field values.
fields
-
An array of
AcroForm
field names the values of which should be used.
Implements parsing of the simplified field notation (SFN).
The argument form
has to be the document’s main AcroForm
object and action_string
has to be the JavaScript action string.
This notation is more powerful than AFSimple_Calculate as it allows arbitrary expressions consisting of additions, substractions, multiplications and divisions, possibly grouped using parentheses, and field names (which stand in for their value) as well as numbers.
Note: The implementation has been created by looking at sample documents using SFN. As such this may not work for all documents that use SFN.