PDF Forms using Form Tag

Available from: v20.3

This tag enables the creation of PDF forms. The tag begins with the string ?form, followed by the key containing the data. There are three types of form elements available:

1. Textboxes
2. Radio Buttons
3. Checkboxes

All three types have common fields that must be provided in order to create them.

• type (required): Indicates which type of form element to be created. Options are text, radio, and checkbox.
• name (required): Unique ID of a form element.
• height (optional): User defined height of a form element. If not specified automatically assigned.
• width (optional): User defined width of a form element. If not specified automatically assigned.
• value (optional): The default value a certain form element will have.
• text (optional): A label for certain form elements.
• selected (optional): Boolean value (true/false) that checks or unchecks radio button elements.

Only form elements fields indicated with required, height and width are common for every element. The remaining elements are discussed in each form elements section below.

Textboxes

To create a textbox form element in a PDF Form, the following fields must be included in the data :

• type (required)
• name (required)
• value (optional)
• height (optional)
• width (optional)

Data Source

SQL

SELECT
    'file1' AS "filename",
    CURSOR (
        SELECT
            CURSOR (
                SELECT
                    'text'       AS "type",
                    ''           AS "value",
                    'first_name' AS "name"
                FROM
                    dual
            ) AS "first_name",
            CURSOR (
                SELECT
                    'text'      AS "type",
                    'Apex R&D'  AS "value",
                    'last_name' AS "name",
                    '20'        AS "height",
                    '200'       AS "width"
                FROM
                    dual
            ) AS "last_name"
        FROM
            dual
    )       AS "data"
FROM
    dual;

PL/SQL returning SQL

DECLARE
    l_return CLOB;
BEGIN
    l_return := q'[
    SELECT
    'file1' AS "filename",
    CURSOR (
        SELECT
            CURSOR (
                SELECT
                    'text'       AS "type",
                    ''           AS "value",
                    'first_name' AS "name"
                FROM
                    dual
            ) AS "first_name",
            CURSOR (
                SELECT
                    'text'      AS "type",
                    'Apex R&D'  AS "value",
                    'last_name' AS "name",
                    '20'        AS "height",
                    '200'       AS "width"
                FROM
                    dual
            ) AS "last_name"
        FROM
            dual
    )       AS "data"
FROM
    dual;
    ]';
    RETURN l_return;
END;

PL/SQL returning JSON

DECLARE
    l_cursor SYS_REFCURSOR;
    l_return CLOB; -- can also be varchar2, make sure it corresponds to the structure in the JSON
BEGIN
    apex_json.initialize_clob_output(dbms_lob.call, TRUE, 2);
    OPEN l_cursor FOR SELECT
                          'file1' AS "filename",
                          CURSOR (
                              SELECT
                                  CURSOR (
                                      SELECT
                                          'text'       AS "type",
                                          ''           AS "value",
                                          'first_name' AS "name"
                                      FROM
                                          dual
                                  ) AS "first_name",
                                  CURSOR (
                                      SELECT
                                          'text'      AS "type",
                                          'Apex R&D'  AS "value",
                                          'last_name' AS "name",
                                          '20'        AS "height",
                                          '200'       AS "width"
                                      FROM
                                          dual
                                  ) AS "last_name"
                              FROM
                                  dual
                          )       AS "data"
                      FROM
                          dual;

    apex_json.write(l_cursor);
    l_return := apex_json.get_clob_output;
    RETURN l_return;
END;

JSON

[
  {
    "filename": "file1",
    "data": [
      {
        "first_name": [{ "type": "text", "name": "first_name" }],
        "last_name": [
          {
            "type": "text",
            "value": "Apex R&D",
            "name": "last_name",
            "height": 20,
            "width": 200
          }
        ]
      }
    ]
  }
]

Template

The template consists of a textbox element with the name first_name and a textbox element with the name last_name, with the form tag represented by

    Name: {?form first_name}   Surname: {?form last_name}

 template.docx  

Output

It will result in two textbox elements in the PDF Form, one with the name first_name and one with the name last_name. The textbox element with the name first_name will be empty with default size, while the textbox element with the name last_name will have the value Apex R&D and will have a height of 20 and a width of 200.

 output.pdf  

Radio Buttons

To create a radio button element, radio type can be used. Extra options for radio type are as follows:

• type (required)
• name (required)
• heigth (optional)
• width (optional)
• value (optional)
• text (optional)
• selected (optional)

There are two ways to create a radio button element. The first way is to create a single radio button element by Referencing. The second way is to create multiple radio button elements by Looping. Multiple radio buttons or Radiolists are grouped together as a single unit, and only one radio button can be selected at a time.

Looping

This technique is used to create a group of radio buttons that are interconnected to each other. A list of items are expected with options for radio type.

SQL

SELECT
    'file1' AS "filename",
    CURSOR (
        SELECT
            CURSOR (
                SELECT
                    'radio'         AS "type",
                    'List A'        AS "value",
                    'Radiolist'     AS "name",
                    'List Option A' AS "text"
                FROM
                    dual
                UNION ALL
                SELECT
                    'radio'         AS "type",
                    'List B'        AS "value",
                    'Radiolist'     AS "name",
                    'List Option B' AS "text",
                    true            AS "selected"
                FROM
                    dual
            ) AS "radiolist"
        FROM
            dual
    )       AS "data"
FROM
    dual;

PL/SQL returning SQL

DECLARE
    l_return CLOB;
BEGIN
    l_return := q'[
    SELECT
    'file1' AS "filename",
    CURSOR (
        SELECT
            CURSOR (
                SELECT
                    'radio'         AS "type",
                    'List A'        AS "value",
                    'Radiolist'     AS "name",
                    'List Option A' AS "text",
                    true            AS "selected"
                FROM
                    dual
                UNION ALL
                SELECT
                    'radio'         AS "type",
                    'List B'        AS "value",
                    'Radiolist'     AS "name",
                    'List Option B' AS "text"
                FROM
                    dual
            ) AS "radiolist"
        FROM
            dual
    )       AS "data"
FROM
    dual;
    ]';
    RETURN l_return;
END;

PL/SQL returning JSON

DECLARE
    l_cursor SYS_REFCURSOR;
    l_return CLOB; -- can also be varchar2, make sure it corresponds to the structure in the JSON
BEGIN
    apex_json.initialize_clob_output(dbms_lob.call, TRUE, 2);
    OPEN l_cursor FOR SELECT
                          'file1' AS "filename",
                          CURSOR (
                              SELECT
                                  CURSOR (
                                      SELECT
                                          'radio'         AS "type",
                                          'List A'        AS "value",
                                          'Radiolist'     AS "name",
                                          'List Option A' AS "text",
                                          1               AS "selected"
                                      FROM
                                          dual
                                      UNION ALL
                                      SELECT
                                          'radio'         AS "type",
                                          'List B'        AS "value",
                                          'Radiolist'     AS "name",
                                          'List Option B' AS "text",
                                          1               AS "selected"
                                      FROM
                                          dual
                                  ) AS "radiolist"
                              FROM
                                  dual
                          )       AS "data"
                      FROM
                          dual;

    apex_json.write(l_cursor);
    l_return := apex_json.get_clob_output;
    RETURN l_return;
END;

JSON

[
  {
    "filename": "file1",
    "data": [
      {
        "radiolist": [
          {
            "type": "radio",
            "value": "List A",
            "name": "Radiolist",
            "text": "List Option A",
            "selected": 1
          },
          {
            "type": "radio",
            "value": "List B",
            "name": "Radiolist",
            "text": "List Option B",
            "selected": 1
          }
        ]
      }
    ]
  }
]

and template :

Radio List : {#radiolist}
  * {?form this} {/radiolist}

Result will look like this:

 template.docx    output.pdf  

Referencing

This technique is used to create a single radio button element. The radio button element is referenced by the name of the radio button element. If multiple radio element are defined, they are not interconnected and will behave as an independent element.

SQL

SELECT
'pdf_form' AS "filename",
CURSOR ( SELECT
    CURSOR (
        SELECT
            CURSOR (
                SELECT
                    'radio'    AS "type",
                    'Radio'    AS "name",
                    'A'        AS "value",
                    'Option A' AS "text",
                    15         AS "height",
                    100        AS "width"
                FROM
                    dual
            ) AS "a",
            CURSOR (
                SELECT
                    'radio'    AS "type",
                    'Radio'    AS "name",
                    'B'        AS "value",
                    'Option B' AS "text",
                    15         AS "height",
                    100        AS "width"
                FROM
                    dual
            ) AS "b"
        FROM
            dual
    ) AS "radio",
FROM
dual
) AS "data" FROM dual;

PL/SQL returning SQL

declare
  l_return clob;
begin
  l_return := q'[
    SELECT
    'pdf_form' AS "filename",
    CURSOR ( SELECT
        CURSOR (
            SELECT
                CURSOR (
                    SELECT
                        'radio'    AS "type",
                        'Radio'    AS "name",
                        'A'        AS "value",
                        'Option A' AS "text",
                        15         AS "height",
                        100        AS "width"
                    FROM
                        dual
                ) AS "a",
                CURSOR (
                    SELECT
                        'radio'    AS "type",
                        'Radio'    AS "name",
                        'B'        AS "value",
                        'Option B' AS "text",
                        15         AS "height",
                        100        AS "width"
                    FROM
                        dual
                ) AS "b"
            FROM
                dual
        ) AS "radio",
    FROM
    dual
    ) AS "data" FROM dual;
    ]';
  return l_return;
end;

PL/SQL returning JSON

declare
  l_cursor sys_refcursor;
  l_return clob; -- can also be varchar2, make sure it corresponds to the structure in the JSON
begin
  apex_json.initialize_clob_output(dbms_lob.call, true, 2);
  open l_cursor for
    SELECT
    'pdf_form' AS "filename",
    CURSOR ( SELECT
        CURSOR (
            SELECT
                CURSOR (
                    SELECT
                        'radio'    AS "type",
                        'Radio'    AS "name",
                        'A'        AS "value",
                        'Option A' AS "text",
                        15         AS "height",
                        100        AS "width"
                    FROM
                        dual
                ) AS "a",
                CURSOR (
                    SELECT
                        'radio'    AS "type",
                        'Radio'    AS "name",
                        'B'        AS "value",
                        'Option B' AS "text",
                        15         AS "height",
                        100        AS "width"
                    FROM
                        dual
                ) AS "b"
            FROM
                dual
        ) AS "radio",
    FROM
    dual
    ) AS "data" FROM dual;

  apex_json.write(l_cursor);
  l_return := apex_json.get_clob_output;
  return l_return;
end;

JSON

[
  {
    "filename": "pdf_form",
    "data": [
      {
        "radio": 
          [{
            "a": [
              {
                "type": "radio",
                "name": "Radio",
                "value": "A",
                "text": "Option A",
                "height": 15,
                "width": 100
              }
            ],
            "b": [
              {
                "type": "radio",
                "name": "Radio",
                "value": "B",
                "text": "Option B",
                "height": 15,
                "width": 100
              }
            ]
          }]
        
      }
    ]
  }
]

and template :

    {?form radio[0].a}
    {?form radio[0].b}

Result will look like this:

 template.docx    output.pdf  

Checkboxes

The checkbox format generates a from woth checkboxes. It has several other options such as :

• type (required)
• name (required)
• heigth (optional)
• width (optional)
• value (optional)
• text (optional)

In this case, the value field can only accept a boolean value, which sets the default state of the checkbox as either checked or unchecked.

Given the data below:

SQL

SELECT
    'file1' AS "filename",
    CURSOR (
        SELECT
            CURSOR (
                SELECT
                    'checkbox'  AS "type",
                    1           AS "value",
                    'Checkbox'  AS "name",
                    'IsChecked' AS "text",
                    20          AS "height",
                    200         AS "width"
                FROM
                    dual
            ) AS "checkbox"
        FROM
            dual
    )       AS "data"
FROM
    dual;

PL/SQL returning SQL

DECLARE
    l_return CLOB;
BEGIN
    l_return := q'[
    SELECT
    'file1' AS "filename",
    CURSOR (
        SELECT
            CURSOR (
                SELECT
                    'checkbox'  AS "type",
                    1           AS "value",
                    'Checkbox'  AS "name",
                    'IsChecked' AS "text",
                    20          AS "height",
                    200         AS "width"
                FROM
                    dual
            ) AS "checkbox"
        FROM
            dual
    )       AS "data"
FROM
    dual;
    ]';
    RETURN l_return;
END;

PL/SQL returning JSON

DECLARE
    l_cursor SYS_REFCURSOR;
    l_return CLOB; -- can also be varchar2, make sure it corresponds to the structure in the JSON
BEGIN
    apex_json.initialize_clob_output(dbms_lob.call, TRUE, 2);
    OPEN l_cursor FOR SELECT
                          'file1' AS "filename",
                          CURSOR (
                              SELECT
                                  CURSOR (
                                      SELECT
                                          'checkbox'  AS "type",
                                          1           AS "value",
                                          'Checkbox'  AS "name",
                                          'IsChecked' AS "text",
                                          20          AS "height",
                                          200         AS "width"
                                      FROM
                                          dual
                                  ) AS "checkbox"
                              FROM
                                  dual
                          )       AS "data"
                      FROM
                          dual;

    apex_json.write(l_cursor);
    l_return := apex_json.get_clob_output;
    RETURN l_return;
END;

JSON

[
  {
    "filename": "file1",
    "data": [
      {
        "checkbox": [
          {
            "type": "checkbox",
            "value": 1,
            "name": "Checkbox",
            "text": "IsChecked",
            "height": 20,
            "width": 200
          }
        ]
      }
    ]
  }
]

Template

{?form checkbox}

Output

 template.docx    output.pdf  

Filling PDF Forms

Available from: v20.2

AOP provides a feature that allows users to fill out forms within PDF files. To use this feature, you need to include an object with the key aop_pdf_form_data in the files array. You can query the available forms by using the form_fields type in the output_type parameter.

There are differeent types of form fields you can fill in :

• Text Fields : You will need to provide the value you want to fill in the field.
• Radio Buttons / Checkboxes : You will need to provide a Boolean value to check or uncheck the field.

If you're not sure which form field name corresponds to each actual field, you can find instructions on how to find it here This will fill in each form field with the name of that field.

Example

Data Source

By providing given data source:

SQL

SELECT
    'file1' AS "filename",
    CURSOR (
        SELECT
            CURSOR (
                SELECT
                    'John'   AS "first_name",
                    'Doe'    AS "last_name",
                    'List A' AS "radiolist",
                    'A'      AS "radio",
                    'true'   AS "Agree"
                FROM
                    dual
            ) AS "aop_pdf_form_data"
        FROM
            dual
    )       AS "data"
FROM
    dual;

PL/SQL returning SQL

DECLARE
    l_return CLOB;
BEGIN
    l_return := q'[
SELECT
    'file1' AS "filename",
    CURSOR (
        SELECT
            CURSOR (
                SELECT
                    'John'   AS "first_name",
                    'Doe'    AS "last_name",
                    'List A' AS "radiolist",
                    'A'      AS "radio",
                    'true'   AS "Agree"
                FROM
                    dual
            ) AS "aop_pdf_form_data"
        FROM
            dual
    )       AS "data"
FROM
    dual;
    ]';
    RETURN l_return;
END;

PL/SQL returning JSON

DECLARE
    l_cursor SYS_REFCURSOR;
    l_return CLOB; -- can also be varchar2, make sure it corresponds to the structure in the JSON
BEGIN
    apex_json.initialize_clob_output(dbms_lob.call, TRUE, 2);
    OPEN l_cursor FOR SELECT
                          'file1' AS "filename",
                          CURSOR (
                              SELECT
                                  CURSOR (
                                      SELECT
                                          'John'   AS "first_name",
                                          'Doe'    AS "last_name",
                                          'List A' AS "radiolist",
                                          'A'      AS "radio",
                                          'true'   AS "Agree"
                                      FROM
                                          dual
                                  ) AS "aop_pdf_form_data"
                              FROM
                                  dual
                          )       AS "data"
                      FROM
                          dual;

    apex_json.write(l_cursor);
    l_return := apex_json.get_clob_output;
    RETURN l_return;
END;

JSON

[
  {
    "filename": "file1",
    "data": [
      {
        "aop_pdf_form_data": [
          {
            "first_name": "John",
            "last_name": "Doe",
            "radiolist": "List A",
            "radio": "A",
            "agree": true
          }
        ]
      }
    ]
  }
]

If you need to specify multiple values in same form field, for example if you have multiple checkboxes with the same name, you can pass it as an array. From AOP 23.2, you can pass it using apex_json prefix in front of the form field name. For example, if you have a checkbox with the name "checkbox1", you can pass it as "apex_json_checkbox1". apex_json prefix parses string values as JSON. For example :

SQL

SELECT
    'file1' AS "filename",
    CURSOR (
        SELECT
            CURSOR (
                SELECT
                json_array(1,0,1) AS "apex_json_checkbox"
                FROM
                    dual
            ) AS "aop_pdf_form_data"
        FROM
            dual
    )       AS "data"
FROM
    dual;
 

PL/SQL returning SQL

declare
  l_return clob;
begin
  l_return := q'[
    SELECT
        'file1' AS "filename",
        CURSOR (
            SELECT
                CURSOR (
                    SELECT
                    json_array(1,0,1) AS "apex_json_checkbox"
                    FROM
                        dual
                ) AS "aop_pdf_form_data"
            FROM
                dual
        )       AS "data"
    FROM
        dual;
    
    ]';
  return l_return;
end;

PL/SQL returning JSON

declare
  l_cursor sys_refcursor;
  l_return clob; -- can also be varchar2, make sure it corresponds to the structure in the JSON
begin
  apex_json.initialize_clob_output(dbms_lob.call, true, 2);
  open l_cursor for
    SELECT
        'file1' AS "filename",
        CURSOR (
            SELECT
                CURSOR (
                    SELECT
                    json_array(1,0,1) AS "apex_json_checkbox"
                    FROM
                        dual
                ) AS "aop_pdf_form_data"
            FROM
                dual
        )       AS "data"
    FROM
        dual;
    

  apex_json.write(l_cursor);
  l_return := apex_json.get_clob_output;
  return l_return;
end;

JSON

[
  {
    "filename": "file1",
    "data": [
      {
        "aop_pdf_form_data": [
          {
            "checkbox": [ 1, 0, 1 ]
          }
        ]
      }
    ]
  }
]

Specifying Font to be used for filling PDF Forms

Available from: v23.1

AOP provides a feature that allows users to specify the font to be used for filling PDF forms. For that, you need to use g_output_form_fill_font present in aop_api_pkg. The font should be installed in the system where AOP is running. You can query the available fonts by visiting here.

Note

AOP expects font name without whitespaces, if your font name is Arial Black, you should use ArialBlack.

Example

SQL

aop_api_pkg.g_output_form_fill_font := 'ArialBlack';

JSON Option

{
  "output": {
    "output_form_fill_font": "ArialBlack"
  }
}

Note

If AOP is unable to find the fontname specified, it will use the fallback font as Arial.

Identifying PDF Form Fields

For filling out forms, or to extract elements that are present in the form fields, you need to know the name of the fields. You can use the identify_form_fields output option to fill in each form field with the name of that field. For that you need to use g_identify_form_fields present in aop_api_pkg.

Example

SQL

aop_api_pkg.g_identify_form_fields := 'true';

JSON Option

{
  "output": {
    "identify_form_fields": true
  }
}

Read Fields from PDF Forms

AOP provides a feature that allows users to read fields from PDF files. Reading fields from PDF forms returns a json object with the field names and values. For that, in your dynamic action you should select PDF Form Fields (PDF) as your output type.

Parse XFA Forms

AOP provides a feature that allows users to parse XFA forms from PDF files. Parsing XFA forms returns a json object with the field names, values and type of the field.

SQL

p_output_type => 'xfa_form_fields',

JSON

{
  "output": {
    "output_type": "xfa_form_fields",
  }
}