How to Work with JavaScript Extensions in .NET

Aspose.PDF FOSS for .NET includes server-side implementations of the PDF JavaScript AF_Date_Format, AF_Number_Format, and AF_Percent_Format functions via the FieldDateTimeFormatter, FieldNumberCurrencyFormatter, and FieldNumberPercentFormatter classes. Install the package with dotnet add package Aspose.Pdf.Foss --version 0.1.0-alpha and use these classes to format AcroForm field values on the server without requiring a JavaScript engine.

Step-by-Step Guide

Step 1: Install the Package

Add Aspose.PDF FOSS to your project:

dotnet add package Aspose.Pdf.Foss --version 0.1.0-alpha

Step 2: Import Required Classes

using Aspose.Pdf.Annotations.JavascriptExtensions;

Step 3: Format a Date/Time Field Value

FieldDateTimeFormatter.Format(dateFormat, dateValue) converts a raw date string according to an Acrobat-style date format pattern. This corresponds to the PDF JavaScript AF_Date_Format function.

string formatted = FieldDateTimeFormatter.Format("mm/dd/yyyy", "2026-06-11");

The dateFormat parameter uses Acrobat date format tokens (e.g., mm, dd, yyyy, HH, MM). When the input dateValue cannot be parsed, the method returns an empty string.

Step 4: Format a Numeric Field as Currency

FieldNumberCurrencyFormatter.Format(precision, sepStyle, negStyle, currencySymbol, isPrependCurrency, fieldValue) formats a numeric string as a currency value. This corresponds to the PDF JavaScript AF_Number_Format function.

var currencyFormatter = new FieldNumberCurrencyFormatter();
string formatted = currencyFormatter.Format(
    precision: 2,
    sepStyle: 0,
    negStyle: 0,
    currencySymbol: "$",
    isPrependCurrency: true,
    fieldValue: "1234.5");

Parameters:

precision - number of decimal places
sepStyle - thousands separator style (0 = comma, 1 = period, 2 = none)
negStyle - negative number style (0 = parentheses, 1 = minus prefix)
currencySymbol - the currency symbol string
isPrependCurrency - true to place the symbol before the number
fieldValue - the raw numeric string to format

Step 5: Format a Numeric Field as a Percentage

FieldNumberPercentFormatter.Format(precision, sepStyle, isPrependPercent, fieldValue) formats a numeric string as a percentage, multiplying the raw value by 100 first. This corresponds to the PDF JavaScript AF_Percent_Format function.

var percentFormatter = new FieldNumberPercentFormatter();
string formatted = percentFormatter.Format(
    precision: 1,
    sepStyle: 0,
    isPrependPercent: false,
    fieldValue: "0.875");

Parameters:

precision - number of decimal places after the decimal point
sepStyle - thousands separator style (0 = comma, 1 = period, 2 = none)
isPrependPercent - true to prepend the % symbol, false to append
fieldValue - the raw numeric string (the formatter multiplies by 100)

Common Issues and Fixes

FieldDateTimeFormatter returns empty string This occurs when the dateValue argument cannot be parsed by the date pattern in dateFormat. Acrobat date tokens differ from .NET DateTime format strings.

FieldNumberCurrencyFormatter produces wrong decimal separator The sepStyle parameter controls the thousands separator. To use a period as the thousands separator, pass sepStyle: 1.

FieldNumberPercentFormatter output is 100x too large The formatter multiplies the input value by 100. If your fieldValue already represents a percentage (e.g., “87.5” instead of “0.875”), divide by 100 before calling Format.

Namespace not found after package install Ensure you are targeting net8.0 or later. The JavascriptExtensions namespace is only available in the Aspose.Pdf.Foss package.

NullReferenceException on empty fieldValue Passing null or an empty string as fieldValue will cause a parse exception. Validate the input before calling Format.

Frequently Asked Questions

What does “corresponds to AF_Date_Format” mean?

PDF AcroForm JavaScript uses AF_Date_Format as the built-in formatting function for date fields. FieldDateTimeFormatter replicates the same formatting logic in .NET managed code so you can apply the same field format strings without executing JavaScript.

Can I use these formatters outside of a PDF document context?

Yes. FieldDateTimeFormatter, FieldNumberCurrencyFormatter, and FieldNumberPercentFormatter are plain classes with no dependency on a Document instance. You can use them in any .NET 8+ context as utility formatters.

What is the difference between FieldNumberCurrencyFormatter and FieldNumberPercentFormatter?

FieldNumberCurrencyFormatter formats a number as a monetary amount without multiplication. FieldNumberPercentFormatter multiplies the input by 100 and appends or prepends a percent symbol.

Is there a way to chain multiple formatters?

No built-in chaining is provided. Apply formatters sequentially in code.

Do I need the full PDF document to use these classes?

No. The formatters operate on plain strings and return formatted strings. They do not require an open Document instance.