PDF Form Builder

GcExcel Templates provide the ability to build PDF forms with various form fields using Excel as the designer. The form fields can be defined using the proper syntax while creating template layouts. After the template is processed, the result can be exported to a PDF document that includes the pre-defined form fields.

The "form" property can be used to define a PDF form field. The value of this property is in JSON format and a JSON string can be used to describe all settings of the form field. For example:

• {{ds1.Name(form={"type": "textbox", "name": "username", "value": "Input your name!","font":{"size":15, "color": "#ff0000", "bold": true}, "required": true})}}

• {{(form={"type": "listbox", "name": "cities", "value": ["Xi'An", "BeiJing"],"font":{"size":11, "color": "#ff00ff", "bold": true}, "required": true})}}

Note: The property name and enum values are case insensitive.

The following standard PDF form fields are supported:

• Check box

• Combo box

• List box

• Button

• Radio button

• Signature

• Text box

Note: The form fields are visible only in PDF documents and not in Excel.

Bound PDF Form

Consider an example for generating a bound PDF form by using GcExcel Templates. In this case, an address book is generated in PDF by defining textbox fields in template cells. The textbox fields are defined in a way that they relate to common details of an address book, like:

Name : {{ds.Name(form={"type": "textbox", "name": "name","font":{"color": "#000000", "bold": true}})}}Email: {{ds.Email(form={"type": "textbox", "name": "Email","font":{"color": "#EC881D"}})}}

These textbox fields are bound fields, whose data is populated from the data source and is displayed in the PDF form after template processing. You can also download the Excel template layout from here.

TextFields[Template].xlsx

After GcExcel processes the template and exports it to a PDF document, the PDF form will look like below:

Unbound PDF Form

Consider an example for generating an unbound PDF form by using GcExcel Templates. In this case, a wage and tax statement is generated in PDF by defining textbox and checkbox fields in template cells, like:

Textbox field:

{{(form={"type": "textbox", "name": "tips","backgroundcolor": "#ffabab"})}}

Checkbox fields:

{{(form={"type": "checkbox", "name": "Retirement","border": {"color": "#ff0000"}})}}

{{(form={"type": "checkbox", "name": "Statutory","border": {"color": "#ff0000"}})}}

These fields are unbound fields, and their data should be filled directly in the PDF form after template processing. You can also download the Excel template layout from here.

TextFields[Template].xlsx

After GcExcel processes the template and exports it to a PDF document, the PDF form will look like below:

Various settings can be applied on form fields to enhance and customize their appearance. These are explained as below:

1. Common Settings

type

• Value Type

  • Enum string

  • Standard Form Fields

    • checkbox

    • textbox

    • listbox

    • combobox

    • radiobutton

    • pushbutton

    • signature

  • Custom Form Fields

    • text

    • date

    • time

    • tel

    • email

    • url

    • password

    • month

    • week

    • number

    • search

• Example

  • {"type": "listbox"}

• Description

  • Indicates the type of form field.

    (Mandatory field)

alternateName

• Value Type

  • String

• Example

  • {"alternateName": "The alt name"}

• Description

  • Displays text which is helpful for a user while filling in the form field. Tooltips appear when the pointer hovers briefly over the form field.

backgroundcolor

• Value Type

  • String

• Example

  • {"backgroundcolor": "#ffff00"}

    {"backgroundcolor": "rgb(255, 178, 0)"}

    {"backgroundcolor": "rgba(188, 100, 0, 255)"}

• Description

  • Indicates background color of the form field.

border - width

• Value Type

  • Yes

• Example

  • {"border":{"width": 120}}

• Description

  • Indicates width, color and style settings of the border for the form field.

border - color

• Value Type

  • String

• Example

  • {"border":{"color": "#ffff00"}

    {"border": {"color": "rgb(255, 178, 0)"}}

    {"border": {"color": "rgba(188, 100, 0, 255)"}}

• Description

  • Indicates width, color and style settings of the border for the form field.

border - style

• Value Type

  • Enum string

    • none

    • solid

    • dashed

    • beveled

    • inset

    • underline

    • unknown

• Example

  • {"border": {"style": "dashed"}}

• Description

  • Indicates width, color and style settings of the border for the form field.

font - size

• Value Type

  • Number

• Example

  • {"font": {"size": 18}}

• Description

  • Indicates various font settings which can be used in the form field.

font - color

• Value Type

  • String

• Example

  • {"font": {"color": "#ffff00"}}

    {"font": {"color": "rgb(255, 178, 0)"}}

    {"font": {"color": "rgba(188, 100, 0, 255)"}}

• Description

  • Indicates various font settings which can be used in the form field.

font - name

• Value Type

  • String

• Example

  • {"font": {"name": "sans-serif"}}

• Description

  • Indicates various font settings which can be used in the form field.

font - bold

• Value Type

  • Boolean

• Example

  • {"font": {"bold": true}}

• Description

  • Indicates various font settings which can be used in the form field.

font - italic

• Value Type

  • Boolean

• Example

  • {"font": {"italic": true}}

• Description

  • Indicates various font settings which can be used in the form field.

locked

• Value Type

  • Boolean

• Example

  • {"locked": true}

• Description

  • Indicates whether the user can change the properties of field or not.

name

• Value Type

  • String

• Example

  • {"name": "The field name"}

• Description

  • Indicates the unique name of field.

readOnly

• Value Type

  • Boolean

• Example

  • {"readOnly": true}

• Description

  • Indicates whether the user can change the value of field or not

required

• Value Type

  • Boolean

• Example

  • {"required": true}

• Description

  • Indicates whether the field must have a value.

printed

• Value Type

  • Boolean

• Example

  • {"printed":false}

• Description

  • Indicates whether to print the field when page is printed.

hidden

• Value Type

  • Boolean

• Example

  • {"hidden":true}

• Description

  • Indicates whether to display the field or not.

mouseUp

• Value Type

  • JsonObject

• Example

  • {"mouseUp":{"script":"fBox1 = this.getField(\"checkbox\");

    fBox1.display = display.hidden", "submit":"http://localhost:80//myscript#FDF", "reset":{"fieldNames":["checkbox", "textbox"]}}}

• Description

  • Indicates background color of the form field.

mouseDown

• Value Type

  • JsonObject

• Example

  • {"mouseDown": {"script":"fBox1= this.getField(\"checkbox\");

    fBox1.display = display.hidden", "submit":"http://localhost:80//myscript#FDF","reset":{"fieldNames": ["checkbox","textbox"]}}}

• Description

  • Indicates the actions to be performed in sequence when the mouse button is pressed in the active area of the field.

mouseEnter

• Value Type

  • JsonObject

• Example

  • {"mouseEnter":{"script":"fBox1= this.getField(\"checkbox\");

    fBox1.display =display.hidden", "submit":"http://localhost:80//myscript#FDF","reset":{"fieldNames": ["checkbox","textbox"]}}}

• Description

  • Indicates the actions to be performed in sequence when the mouse button enters the field's active area.

mouseExit

• Value Type

  • JsonObject

• Example

  • {"mouseExit":{"script":"fBox1= this.getField(\"checkbox\");

    fBox1.display =display.hidden", "submit":"http://localhost:80//myscript#FDF","reset":{"fieldNames": ["checkbox","textbox"]}}}

• Description

  • Indicates the actions to be performed in sequence when the mouse button exitsthe field's active area.

onFocus

• Value Type

  • JsonObject

• Example

  • {"onFocus":{"script":"fBox1 = this.getField(\"checkbox\");

    fBox1.display =display.hidden", "submit":"http://localhost:80//myscript#FDF","reset":{"fieldNames": ["checkbox","textbox"]}}}

• Description

  • Indicates the actions to be performed in sequence when the annotation receives the input focus.

onBlur

• Value Type

  • JsonObject

• Example

  • {"onBlur":{"script":"fBox1= this.getField(\"checkbox\");

    fBox1.display =display.hidden", "submit":"http://localhost:80//myscript#FDF","reset":{"fieldNames": ["checkbox","textbox"]}}}

• Description

  • Indicates the actions to be performed in sequence when the annotation loses the input focus.

format

• Value Type

  • String

• Example

  • {"format":"event.value = (event.value * 100) + \" % \";"}

• Description

  • 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

• Value Type

  • String

• Example

  • {"validate":"if (event.value < 0

    || event.value > 100)

    {\r\n" +"app.beep(0);\r\n"

    +"app.alert(\"Invalid value for field \"

    +event.target.name);\r\n" +

    "event.rc = false;\r\n" +"}"}

• Description

  • Indicates a JavaScript action to be performed when the field’s value is changed. This action can check the new value for validity.

calculate

• Value Type

  • String

• Example

  • {"calculate":"var oil =

    this.getField(\"Oil\");\r\n"+

    "var filter = this.getField(\"Filter\")

    ;\r\n"+"event.value

    (oil.value + filter.value) * 1.0825;"}

• Description

  • Indicates a JavaScript action to be performed to recalculate the value of this field when that of another field changes.

keystroke

• Value Type

  • String

• Example

  • {"keystroke":"if (!event.willCommit)

    {\r\n"+"var f =this.getField

    (\"myPictures\");\r\n"+"var i =this.getIcon(event.change)

    ;\r\n"+"f.buttonSetIcon(i);\r\n"+"};"}

• Description

  • Indicates a JavaScript action to be performedwhen 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.

autofocus

• Value Type

  • Boolean

• Example

  • {"type": "password", "autofocus": true}

• Description

  • Indicates whether a date field should automatically get focus when the page loads.

disabled

• Value Type

  • Boolean

• Example

  • {"type": "password", "disabled": true}

• Description

  • Indicates whether a field is disabled or not.

autocomplete

• Value Type

  • Enum String

    • on

    • off

    • name

    • honorific-prefix

    • given-name

    • additional-name

    • family-name

    • honorific-suffix

    • nickname

    • email

    • username

    • new-password

    • current-password

    • one-time-code

    • organization-title

    • organization

    • street-address

    • address-line1

    • address-line2

    • address-line3

    • address-level4

    • country

    • country-name

    • postal-code

    • cc-name

    • cc-given-name

    • cc-additional-name

    • cc-family-name

    • cc-number

    • cc-exp

    • cc-exp-month

    • cc-exp-year

    • cc-csc

    • cc-type

    • transaction-currency

    • transaction-amount

    • bday-day

    • language

    • bday

    • bday-day

    • bday-month

    • bday-year

    • sex

    • tel

    • tel-country-code

    • tel-national

    • tel-area-code

    • tel-local

    • tel-local-prefix

    • tel-local-suffix

    • tel-extension

    • impp

    • url

    • photo

• Example

  • {"type": "date", "autocomplete": "bday"}

• Description

  • Let web developers specify if any user needs to provide assistance for automated filling of form field values, as well as guidance to the browser about what type of information is expected in the field.

    The behavior of this property depends on the browser implementation.

2. JsonObject Settings

type=warning

Note: Snippets of JavaScript code needs to be escaped.

3. Checkbox Form Field Settings

4. Textbox Form Field Settings

type=warning

Note: GcExcel also supports custom form fields like date, email, password, month etc. which are inherited from Textbox form field. To know more about these, refer Custom Form Fields.

5. Listbox Form Field Settings

6. Combobox Form Field Settings

7. Radiobutton Form Field Settings

8. Pushbutton Form Field Settings

9. Signature Form Field Settings

type=warning

Note: GcExcel Template generates only digital signature fields in PDF documents. If you want to add signatures on signature fields, you need to use GcPDF or PDFBox to process.

Apart from the above mentioned standard PDF form fields, GcExcel also supports custom form input types to generate PDF forms. Refer to Custom Form Input Types for more information.