Generate PDF Forms with GrapeCity Documents for Excel (.NET and Java)

PDF Forms are very useful for sending portable cross-platform documents to users who open documents using a variety of client-side tools on a variety of platforms and fill in the form fields, then save to a new PDF document with the form field values retained in the file.

The file is returned or forwarded to whoever needs to process the form, and automated tools easily extract the form fields from the file. This is a common use case for many forms such as surveys and questionnaires, healthcare forms for release of records or insurance, and legal and tax forms.

Now GrapeCity Documents for Excel makes it easy to create rich and complex PDF Forms from Excel Template spreadsheet documents. Creating a PDF Form is easy; by utilizing the form layout in an Excel Template worksheet and a special template syntax in the cells where the PDF Form fields are placed in the document.

The syntax is rich and versatile, supporting many PDF Form field properties including many event handlers which have JavaScript actions attached using JavaScript for Acrobat.

JSON Syntax for PDF Fields

GrapeCity Documents for Excel uses the mustache syntax of Excel Template worksheets with new support for the form property to specify a PDF Form Field. The PDF Form Field properties are specified using standard JSON syntax and can include snippets of JavaScript code. Here are some examples of the new PDF Form Field syntax:

  1. {{ds1.Team(R=B6:F7, form={"type": "checkbox", "name": "teams","font":{"size":10, "color": "#ffff00", "bold": true}, "checkstyle": "Circle"})}}
  2. {{ds1.Name(form={"type": "textbox", "name": "username", "value": "Input your name!","font":{"size":15, "color": "#ff0000", "bold": true}, "required": true})}}
  3. {{(form={"type": "listbox", "name": "cities", "value": ["Xi'An", "BeiJing"],"font":{"size":11, "color": "#ff00ff", "bold": true}, "required": true})}}
  4. {{(form={"type": "combobox", "name": "dates", "value": ["2019", "2020", "2021", "2022"],"font":{"size":11, "color": "#ff00ff", "bold": true}, "required": true})}}

Example 1 specifies a checkbox field named teams using a font with size 10, yellow color and bold text, with a checkstyle of Circle style checkbox.

Example 2 specifies a textbox field named username with value "Input your name!" and font with size 15, red color and bold text, with the field being a required field in the form.

Example 3 specifies a listbox field named cities with value showing the JavaScript array of strings ["Xi'An", "BeiJing"] using a font with size 11, magenta color and bold text, with the field being a required field in the form.

Example 4 specifies a combobox field named dates with value showing the JavaScript array of strings listing the years 2019-2022 using a font with size 11, magenta color and bold text, with the field being a required field in the form.

Common PDF Form Field Properties

There are many PDF Form Field properties as shown in the examples above which can be applied to any PDF Form Field type. The identifiers named and described in the following table are not case-sensitive:

Note: The table below is an excerpt of the full table in the documentation here – please see the documentation for value types and examples.

Name Description
type Indicates the type of the field.
alternateName Displays tooltip text on hover over the field that the hesitant user may find helpful in filling in the form field.
backgroundcolor Specifies the background color of the field.
border Specifies the border around the field.
font Specifies the font of the field.
locked Indicates whether the user can change the properties of the field.
Name Indicates the unique name of the field.
readOnly Indicates whether the user can change the value of the field.
required Indicates whether the field must have a value for the form to process.
printed Indicates if specified field is printed with all other fields on document (when print is selected by a user).
hidden Indicates whether to display the field on the screen.
mouseUp Indicates the actions to be performed in sequence when the mouse button is released in the active area of the field.
mouseDown Indicates the actions to be performed in sequence when the mouse button is pressed in the active area of the field.
mouseEnter Indicates the actions to be performed in sequence when the mouse button enters the field's active area.
mouseExit Indicates the actions to be performed in sequence when the mouse button exits the field's active area.
onFocus Indicates the actions to be performed in sequence when the annotation receives the input focus.
onBlur Indicates the actions to be performed in sequence when the annotation loses the input focus.
format Indicates a JavaScript action to be performed before the field is formatted to display its current value. This action can modify the field’s value before formatting.
validate Indicates a JavaScript action to be performed when the field’s value is changed. This action can check the new value for validity.
calculate Indicates a JavaScript action to be performed to recalculate the value of this field when that of another field changes.
keystroke Indicates a JavaScript action to be performed when the user types a keystroke into a text field or combo box or modifies the selection in a scrollable list box. This action can check the keystroke for validity and reject or modify it.

Action JSON Object

Many of the properties for event handlers above use a special Action JSON Object to specify the behavior, which enables the creation of complex reactive and dynamic forms. Please note that the JavaScript specified must use escaped characters to embed quotes, linefeeds, carriage return, and other characters that require escaping when embedded inside JSON. The Action JSON Object has the following properties (which are also not case-sensitive):

Note: The table below is an excerpt of the full table in the documentation here – please see the documentation for value types and examples.

Name Description
script Indicates an action causes a script to be compiled and executed by the JavaScript interpreter.
submit Indicates an action transmits the names and values of selected interactive form fields to a specified uniform resource locator (URL), presumably the address of a Web server that will process them and send back a response.
reset A JSON objecty which describes the field names to include or exclude in the reset operation.

Type-Specific PDF Form Field Properties

Some PDF Form Field properties are only applicable to specific PDF Form Field types. The following tables list the properties available for each PDF Form Field type:

Checkbox specific settings

Note: The table below is an excerpt of the full table in the documentation here – please see the documentation for value types and examples.

Name Description
checkStyle The style of check mark.
value If this value is missing, GcExcel will automatically try converting the cell's value to Boolean, and then, set it to the property after template processing.
defaultValue Value indicating whether the checkbox is checked when the user first opens the form.
Textbox specific settings

Note: The table below is an excerpt of the full table in the documentation here – please see the documentation for value types and examples.

Name Description
value The value to show in the textbox.
defaultValue The default value to show in the textbox when the user first opens the form.
combo Indicating whether the new value is committed as soon as a selection is made with the pointing device.
password Indicating whether the field is intended for entering a secure password that should not be echoed visibly to the screen.
spellcheck Indicating whether the text entered in the field is spell-checked.
scrollable Indicating whether the field is scrollable to accommodate more text than fits within its annotation rectangle.
maxLen The maximum length of the field’s text, in characters.
multiline Indicating whether the field can contain multiple lines of text.
justification The justification to be used in displaying the field’s text.
Listbox specific settings

Note: The table below is an excerpt of the full table in the documentation here – please see the documentation for value types and examples.

Name Description
value The list of items to show in the listbox.
commitOnSelChange Indicates whether the new value is committed as soon as a selection is made with the pointing device.
selectedIndex The index of selected item (if there is one item selected).
sort Indicates whether the field’s option items should be sorted alphabetically.
selectedIndexes The indexes of selected items (if more than one item is selected).
multiSelect Indicates whether more than one of the field’s option items may be selected simultaneously.
exportValue The export value of this list box field.
Combobox specific settings

Note: The table below is an excerpt of the full table in the documentation here – please see the documentation for value types and examples.

Name Description
value The list of items to show in the combobox.
commitOnSelChange Indicates whether the new value is committed as soon as a selection is made with the pointing device.
selectedIndex The indexes of selected item.
sort Indicates whether the field’s option items should be sorted alphabetically.
spellCheck Indicates whether the text entered in the field is spell-checked.
editable Indicates whether the combo box includes an editable text box as well as a drop-down list.
exportValue The export value of this combo box field.
Radiobutton specific settings

Note: The table below is an excerpt of the full table in the documentation here – please see the documentation for value types and examples.

Name Description
checkStyle The style of check mark.
groupName The name of the radio button group. Radio buttons with the same group name, will be added in the same group. If this value is missing, GcExcel will automatically add radio buttons expanded from the same template cell to the same group after template processing.
radiosInUnison Indicates whether a group of radio buttons within a radio button field that use the same value for the on state will turn on and off in unison; That is, if one is checked, they are all checked. If clear, the buttons are mutually exclusive (the same behavior as HTML radio buttons).
checkedChoice Indicates a value which option is checked.
defaultCheckedChoice Indicates a value which option is checked when the user first opens the form.

Radio buttons with the same groupName belong to the same group. RadiosInUnison, checkedChoice, defaultCheckedChoice: these three settings belong to the radio button group, and the values of the these settings are based on the last specified.

Pushbutton specific settings:

Note: The table below is an excerpt of the full table in the documentation here – please see the documentation for value types and examples.

Name Description
highlighting Indicates the annotation’s highlighting mode.
caption Indicates the button's caption.
image Indicates the button’s image.
captionImageRelation Indicates how to position the button's caption relative to image.
downCaption Indicates the button's caption when user presses the button.
downImage Indicates the button’s image when user presses the button.
rolloverCaption Indicates the button's caption when the user rolls the cursor into its active area without pressing the mouse button.
rolloverImage Indicates the button’s image when the user rolls the cursor into its active area without pressing the mouse button.
imageScale Indicates the image scaling.
Signature specific settings

Note: The table below is an excerpt of the full table in the documentation here – please see the documentation for value types and examples.

Name Description
lockType Indicates the type of the locked fields.
fieldNames Indicates the list of fields' names which should be included / excluded from processing depending on lockType property.
LockedFields Indicates whether to lock the fields when SignatureFormField is signed.

Data Binding to Excel Templates with PDF Form Fields

You can also use data binding in the Excel Template to specify values for the PDF Form Fields using a data source. All the Enhanced Excel Template Data Binding features work with the new PDF Form Fields and can specify the initial values in the PDF Form Field cells. An example is included in the new demo samples for the textbox field which creates an Address Book:

Figure 1 - Textbox PDF Form Field sample Excel Template for Address Book:

Textbox PDF Form Field sample Excel Template for Address Book

This sample uses the data binding feature to populate values to the cells in the table, which are also using textbox PDF Form Fields to allow editing of the values in the PDF. The code for this follows:

NET C# Code

//create a new workbook
var workbook = new GrapeCity.Documents.Excel.Workbook();

//Load template file from resource
var templateFile = this.GetResourceStream("xlsx\\Template_TextFields.xlsx");
workbook.Open(templateFile);

#region Init Data
var datasource = new DataTable();
datasource.Columns.Add(new DataColumn("Name", typeof(string)));
datasource.Columns.Add(new DataColumn("Work", typeof(string)));
datasource.Columns.Add(new DataColumn("Cell", typeof(string)));
datasource.Columns.Add(new DataColumn("Home", typeof(string)));
datasource.Columns.Add(new DataColumn("Email", typeof(string)));
datasource.Columns.Add(new DataColumn("Birthday", typeof(string)));
datasource.Columns.Add(new DataColumn("Address", typeof(string)));
datasource.Columns.Add(new DataColumn("City", typeof(string)));
datasource.Columns.Add(new DataColumn("State", typeof(string)));
datasource.Columns.Add(new DataColumn("Zip", typeof(string)));

datasource.Rows.Add("Kim Abercrombie", "1235550123", "1235550123", "1235550123", "Kim@example.com", "4/13/1991", "123 N. Maple", "Cherryville", "WA", "98031");
datasource.Rows.Add("John Smith", "3215230123", "3215230123", "3215230123", "John@example.com", "5/20/1990", "4456 E. Aspen", "Montgomery", "AL", "36136");
datasource.Rows.Add("James Williams", "5235550879", "5235550879", "5235550879", "James@example.com", "4/5/1995", "123 N. Maple", "Denver", "CO", "80214");
datasource.Rows.Add("Mark Jordan", "1238640185", "1238640185", "1238640185", "Mark@example.com", "12/13/1988", "123 N. Maple", "Boise", "ID", "83706");
datasource.Rows.Add("Andrew Lepp", "6235320178", "6235320178", "6235320178", "Andrew@example.com", "10/9/1996", "123 N. Maple", "Augusta", "ME", "04336");
#endregion

//Add data source
workbook.AddDataSource("ds", datasource);

//Invoke to process the template
workbook.ProcessTemplate();

//save to a pdf file
workbook.Save("textfields.pdf");

.NET VB Code

' Create a new Workbook
Dim workbook As New Workbook
'Load template file from resource
Dim templateFile = GetResourceStream("xlsx\Template_TextFields.xlsx")
workbook.Open(templateFile)

#Region "Init Data"
Dim datasource As New DataTable
With datasource.Columns
    .Add(New DataColumn("Name", GetType(String)))
    .Add(New DataColumn("Work", GetType(String)))
    .Add(New DataColumn("Cell", GetType(String)))
    .Add(New DataColumn("Home", GetType(String)))
    .Add(New DataColumn("Email", GetType(String)))
    .Add(New DataColumn("Birthday", GetType(String)))
    .Add(New DataColumn("Address", GetType(String)))
    .Add(New DataColumn("City", GetType(String)))
    .Add(New DataColumn("State", GetType(String)))
    .Add(New DataColumn("Zip", GetType(String)))
End With

With datasource.Rows
    .Add("Kim Abercrombie", "1235550123", "1235550123", "1235550123", "Kim@example.com", "4/13/1991", "123 N. Maple", "Cherryville", "WA", "98031")
    .Add("John Smith", "3215230123", "3215230123", "3215230123", "John@example.com", "5/20/1990", "4456 E. Aspen", "Montgomery", "AL", "36136")
    .Add("James Williams", "5235550879", "5235550879", "5235550879", "James@example.com", "4/5/1995", "123 N. Maple", "Denver", "CO", "80214")
    .Add("Mark Jordan", "1238640185", "1238640185", "1238640185", "Mark@example.com", "12/13/1988", "123 N. Maple", "Boise", "ID", "83706")
    .Add("Andrew Lepp", "6235320178", "6235320178", "6235320178", "Andrew@example.com", "10/9/1996", "123 N. Maple", "Augusta", "ME", "04336")
End With
#End Region

'Add data source
workbook.AddDataSource("ds", datasource)

'Invoke to process the template
workbook.ProcessTemplate()

' save to a pdf file
workbook.Save("textfields.pdf")

Java Code

//create a new workbook
Workbook workbook = new Workbook();
// Load template file from resource
InputStream templateFile = this.getResourceStream("xlsx/Template_TextFields.xlsx");
workbook.open(templateFile);

// #region Init Data
List<AddressBook> addressBooks = new ArrayList<AddressBook>();

AddressBook addressBook1 = new AddressBook();
addressBook1.name = "Kim Abercrombie";
addressBook1.work = "1235550123";
addressBook1.cell = "1235550123";
addressBook1.home = "1235550123";
addressBook1.email = "Kim@example.com";
addressBook1.birthday = "4/13/1991";
addressBook1.address = "123 N. Maple";
addressBook1.city = "Cherryville";
addressBook1.state = "WA";
addressBook1.zip = "98031";
addressBooks.add(addressBook1);

AddressBook addressBook2 = new AddressBook();
addressBook2.name = "John Smith";
addressBook2.work = "3215230123";
addressBook2.cell = "3215230123";
addressBook2.home = "3215230123";
addressBook2.email = "John@example.com";
addressBook2.birthday = "5/20/1990";
addressBook2.address = "4456 E. Aspen";
addressBook2.city = "Montgomery";
addressBook2.state = "AL";
addressBook2.zip = "36136";
addressBooks.add(addressBook2);

AddressBook addressBook3 = new AddressBook();
addressBook3.name = "James Williams";
addressBook3.work = "5235550879";
addressBook3.cell = "5235550879";
addressBook3.home = "5235550879";
addressBook3.email = "James@example.com";
addressBook3.birthday = "4/5/1995";
addressBook3.address = "123 N. Maple";
addressBook3.city = "Denver";
addressBook3.state = "CO";
addressBook3.zip = "80214";
addressBooks.add(addressBook3);

AddressBook addressBook4 = new AddressBook();
addressBook4.name = "Mark Jordan";
addressBook4.work = "1238640185";
addressBook4.cell = "1238640185";
addressBook4.home = "1238640185";
addressBook4.email = "Mark@example.com";
addressBook4.birthday = "12/13/1988";
addressBook4.address = "123 N. Maple";
addressBook4.city = "Boise";
addressBook4.state = "ID";
addressBook4.zip = "83706";
addressBooks.add(addressBook4);

AddressBook addressBook5 = new AddressBook();
addressBook5.name = "Andrew Lepp";
addressBook5.work = "6235320178";
addressBook5.cell = "6235320178";
addressBook5.home = "6235320178";
addressBook5.email = "Andrew@example.com";
addressBook5.birthday = "10/9/1996";
addressBook5.address = "123 N. Maple";
addressBook5.city = "Augusta";
addressBook5.state = "ME";
addressBook5.zip = "04336";
addressBooks.add(addressBook5);
// #endregion

// Add data source
workbook.addDataSource("ds", addressBooks);

// Invoke to process the template
workbook.processTemplate();

//save to an pdf file
workbook.save("TextFields.pdf");

Kotlin Code

//create a new workbook
var workbook = Workbook()
// Load template file from resource
val templateFile = this.getResourceStream("xlsx/Template_TextFields.xlsx")
workbook.open(templateFile)

// #region Init Data
val addressBooks = ArrayList<AddressBook>()

val addressBook1 = AddressBook()
addressBook1.name = "Kim Abercrombie"
addressBook1.work = "1235550123"
addressBook1.cell = "1235550123"
addressBook1.home = "1235550123"
addressBook1.email = "Kim@example.com"
addressBook1.birthday = "4/13/1991"
addressBook1.address = "123 N. Maple"
addressBook1.city = "Cherryville"
addressBook1.state = "WA"
addressBook1.zip = "98031"
addressBooks.add(addressBook1)

val addressBook2 = AddressBook()
addressBook2.name = "John Smith"
addressBook2.work = "3215230123"
addressBook2.cell = "3215230123"
addressBook2.home = "3215230123"
addressBook2.email = "John@example.com"
addressBook2.birthday = "5/20/1990"
addressBook2.address = "4456 E. Aspen"
addressBook2.city = "Montgomery"
addressBook2.state = "AL"
addressBook2.zip = "36136"
addressBooks.add(addressBook2)

val addressBook3 = AddressBook()
addressBook3.name = "James Williams"
addressBook3.work = "5235550879"
addressBook3.cell = "5235550879"
addressBook3.home = "5235550879"
addressBook3.email = "James@example.com"
addressBook3.birthday = "4/5/1995"
addressBook3.address = "123 N. Maple"
addressBook3.city = "Denver"
addressBook3.state = "CO"
addressBook3.zip = "80214"
addressBooks.add(addressBook3)

val addressBook4 = AddressBook()
addressBook4.name = "Mark Jordan"
addressBook4.work = "1238640185"
addressBook4.cell = "1238640185"
addressBook4.home = "1238640185"
addressBook4.email = "Mark@example.com"
addressBook4.birthday = "12/13/1988"
addressBook4.address = "123 N. Maple"
addressBook4.city = "Boise"
addressBook4.state = "ID"
addressBook4.zip = "83706"
addressBooks.add(addressBook4)

val addressBook5 = AddressBook()
addressBook5.name = "Andrew Lepp"
addressBook5.work = "6235320178"
addressBook5.cell = "6235320178"
addressBook5.home = "6235320178"
addressBook5.email = "Andrew@example.com"
addressBook5.birthday = "10/9/1996"
addressBook5.address = "123 N. Maple"
addressBook5.city = "Augusta"
addressBook5.state = "ME"
addressBook5.zip = "04336"
addressBooks.add(addressBook5)
// #endregion

// Add data source
workbook.addDataSource("ds", addressBooks)

// Invoke to process the template
workbook.processTemplate()

//save to an pdf file
workbook.save("TextFields.pdf")

The code above opens the Excel Template workbook and then creates and adds a data source with the address values to bind to the template cells, and finally processes the template and saves the PDF.

Figure 2 - Editable Address Book PDF form showing in GcPdfViewer:

Editable Address Book PDF form showing in GcPdfViewer

Embedded Fonts for PDF Form Fields

By default, a font specified for a PDF Form Field will be embedded in the PDF. Embedding the font ensures that all glyphs are available for the user to type freely in the form fields and that those glyphs can be used to render the user's input. However, embedding the entire font can greatly increase the file size, especially in the case of some common Unicode and Asian fonts which contain many character sets for various languages. To avoid very large files, you can explicitly in the Excel Template that you do not want to embed the fonts for the PDF Form Fields created with GrapeCity Documents for Excel v3.2 using the global option TemplateOptions.EmbedFontForFormFields. This global option is specified in the Excel Template workbook using a workbook-level name:

NET C# Code

//Init template global settings
workbook.Names.Add("TemplateOptions.EmbedFontForFormFields", "false");

.NET VB Code

//Init template global settings
workbook.Names.Add("TemplateOptions.EmbedFontForFormFields", "false")

Java Code

//Init template global settings
workbook.getNames().add("TemplateOptions.EmbedFontForFormFields", "false");

Kotlin Code

//Init template global settings
workbook.getNames().add("TemplateOptions.EmbedFontForFormFields", "false")

Example PDF Form: US Tax Form W-4

Figure 3 - US Tax Form W-4:

US Tax Form W-4

You can find this example creating a fillable US Tax Form W-4 in the new demo samples (for .NET here and for Java/Kotlin here) for GrapeCity Documents for Excel v3.2. This example creates the PDF Form Fields using the Excel Template shown above, which can be downloaded from the demo here for .NET or here for Java using the "Download Template" button .

In the template, you can see the PDF Form Field cells using the mustache syntax to specify the properties for the fields. In cell B7 the first textbox PDF Form Field appears:

{{(form={"type": "textbox", "name": "First&Middle Name", "font":{"bold":true, "color": "#362EA2"}})}}

This specifies a textbox named First&Middle Name with font with a dark blue-purple color and bold text. Other textbox fields appear in cell I7 for Last Name, O7 for Social Security Number, B9 for Address, and B11 for Address2 (City or town, state, and ZIP code).

Next in cell C12 the first checkbox field appears:

{{(form={"type": "checkbox", "name": "Single","border": {"color": "#000000"}})}}This specifies a checkbox named Single with a black color border. There are other checkbox fields in cells C13 for Married, C14 for HouseHold, and S23 for TwoJobs.

This example does not use signature fields, as the actual US W-4 does not, but if it did then it would be specified in cell B46 like this:

{{(form={"type": "signature", "name": "Employee's Signature", "font":{"bold":true, "color": "#362EA2"}})}}

The code to create this US W-4 Tax Form from the Template Spreadsheet follows:

NET C# Code

//create a new workbook
var workbook = new GrapeCity.Documents.Excel.Workbook();

//Load template file from resource
var templateFile = this.GetResourceStream("xlsx\\Template_fw4-USTaxForm.xlsx");
workbook.Open(templateFile);

//Invoke to process the template
workbook.ProcessTemplate();

//save to a pdf file
workbook.Save("ustaxform_fw4.pdf");

.NET VB Code

' Create a new Workbook
Dim workbook As New Workbook
'Load template file from resource
Dim templateFile = GetResourceStream("xlsx\Template_fw4-USTaxForm.xlsx")
workbook.Open(templateFile)


'Invoke to process the template
workbook.ProcessTemplate()

' save to a pdf file
workbook.Save("ustaxform_fw4.pdf")

Java Code

//create a new workbook
Workbook workbook = new Workbook();
//Load template file from resource
InputStream templateFile = this.getResourceStream("xlsx/Template_fw4-USTaxForm.xlsx");
workbook.open(templateFile);

//Invoke to process the template
workbook.processTemplate();

//save to an pdf file
workbook.save("USTaxForm_fw4.pdf");

Kotlin Code

//create a new workbook
var workbook = Workbook()
//Load template file from resource
val templateFile = this.getResourceStream("xlsx/Template_fw4-USTaxForm.xlsx")
workbook.open(templateFile)

//Invoke to process the template
workbook.processTemplate()

//save to an pdf file
workbook.save("USTaxForm_fw4.pdf")

Figure 4 - US W-4 Tax Form in GcPdfViewer:

US W-4 Tax Form in GcPdfViewer

This demo sample is available in the new GrapeCity Documents for Excel demos for both .NET and Java versions here: US Tax Form Example .NET and US Tax Form Example Java

Download your free trial of GrapeCity Documents for Excel v3.2 for .NET here or for Java here today!

Sean Lawyer

Sean Lawyer

Product Manager
comments powered by Disqus