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:

Calculating a field’s value

The main entry point is calculate which calculates a field’s value. Supported JavaScript actions are:

See: PDF2.0 s12.6.4.17

See:

Constants

AF_NUMBER_FORMAT_RE

Regular expression for matching the AFNumber_Format method.

See: apply_af_number_format

AF_PERCENT_FORMAT_RE

Regular expression for matching the AFPercent_Format method.

See: apply_af_percent_format

AF_SIMPLE_CALCULATE

Mapping of AFSimple_Calculate function names to implementations.

See: run_af_simple_calculate

AF_SIMPLE_CALCULATE_RE

Regular expression for matching the AFSimple_Calculate function.

See: run_af_simple_calculate

AF_TIME_FORMAT_RE

Regular expression for matching the AFTime_Format method.

See: apply_af_time_format

Public Instance Methods

af_format_number(value, format, sep_style)

Formats the numeric value according to the format string and separator style.

af_make_number(value)

Returns the numeric value of the string, interpreting comma as point.

af_number_format_action(decimals: 2, separator_style: :point, negative_style: :minus_black, currency_string: "", prepend_currency: true)

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).

See: apply_af_number_format

af_percent_format_action(decimals: 2, separator_style: :point)

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.

See: apply_af_percent_format

af_simple_calculate_action(type, fields)

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.

See: run_af_simple_calculate

af_time_format_action(format: :hh_mm)

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

apply_af_number_format(value, action_string)

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).

apply_af_percent_format(value, action_string)

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

apply_af_time_format(value, action_string)

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

apply_format(value, format_action)

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.

calculate(form, calculate_action)

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).

run_af_simple_calculate(form, action_string)

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.

run_simplified_field_notation(form, action_string)

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.

simplified_field_notation_action(form, sfn_string)

Returns the appropriate JavaScript action string for a calculate action that uses Simplified Field Notation.

The argument form has to be the document’s main AcroForm object and sfn_string the string containing the simplified field notation.

See: run_simplified_field_notation