Home » Newsletter » June 2016

by Santosh Patil

Select the language for the code snippets C# Delphi Java JavaScript

If you are new to StarDocs, we suggest you read the introductory article and the getting started article first. This article builds on the steps explained in those foundational articles to avoid repetition.

The API reference documentation can be found here.

PDF forms are often employed for online data-collection. They help reduce paper usage and overcome the cumbersome process of data import. Using our HTML5 viewer you can easily display a form to a user and collect the filled-in values via the HTTP submit action. Subsequently there may be a need to populate a blank form with the collected values. In this article we'll show you how to fill the values back into the form fields contained in a PDF file and optionally flatten (finalize) the fields. The filled-in form can then be displayed back to the user, processed further or downloaded and printed.

1. After authentication and uploading of the PDF file containing form fields you will get the document URL. Using the document URL you can request for filling up the form as shown below.

// Set up connection details
var stardocs = new Gnostice.StarDocs(
  new Gnostice.ConnectionInfo(
    'https://api.gnostice.com/stardocs/v1', 
    '<API Key>', 
    '<API Secret>'),
  new Preferences(
    // Whether to force full permissions on PDF files protected 
    // with an permissions/owner/master password
    new DocPasswordSettings(true))
);

// Authenticate
stardocs.auth.loginApp()
  .done(function(response) {
    // Upload file
    var selectedFile = document.getElementById('input').files[0];
    stardocs.storage.upload(selectedFile) 
      .done(function(response) {
        var documentUrl = response.documents[0].url;
        // Form field values
        var formFields = [
          {
            fieldName: "txtFirstName",
            fieldValue: "Nikita",
            flattenField: true
          },
          {
            fieldName: "radioGender",
            fieldValue: "radioFemale",
            flattenField: true
          },
          {
            fieldName: "listboxLanguages",
            fieldValue: "Russian,English"
          }
        ];
        // Fill form, optionally specifying the 
        // password if the document is encrypted
        stardocs.docOperations.fillForm(documentUrl, "password", formFields)
          .done(function(response) {
            var filledDocumentUrl = response.documents[0].url;
            // Do something with filledDocumentUrl
            // ...
          });
      });
  });

// Set up connection details
StarDocs starDocs = new StarDocs(
  new ConnectionInfo(
    new Uri("https://api.gnostice.com/stardocs/v1"),
    "<API Key>",
    "<API Secret>"), 
  new Preferences(
    // Whether to force full permissions on PDF files protected 
    // with an permissions/owner/master password
    new DocPasswordSettings(true))
);

// Authenticate
starDocs.Auth.loginApp();

// Upload file, optionally specifying the password if the document 
// is encrypted
DocObject docObjectSurveyForm = starDocs.Storage.Upload(
  @"C:\Documents\SurveyForm_blank.pdf", "password");

// Form field values
List<PDFFormFieldFillData> formFields = 
  new List<PDFFormFieldFillData>();
formFields.Add(
  new PDFFormFieldFillData("txtFirstName", "Nikita", true));
formFields.Add(
  new PDFFormFieldFillData("radioGender", "radioFemale", true));
formFields.Add(
  new PDFFormFieldFillData("listboxLanguages", "Russian,English"));

// Fill form
DocObject docObjectSurveyFormFilled = 
  starDocs.DocOperations.FillForm(docObjectBalanceSheet, null, 
    formFields);

// Do something with docObjectSurveyFormFilled
// ...

// Set up connection details
StarDocs starDocs = new StarDocs(
  new ConnectionInfo(
    new java.net.URI("https://api.gnostice.com/stardocs/v1"),
    "<API Key>",
    "<API Secret>"), 
  new Preferences(
    // Whether to force full permissions on PDF files protected 
    // with an permissions/owner/master password
    new DocPasswordSettings(true))
);

// Authenticate
starDocs.auth.loginApp();

// Upload file, optionally specifying the password if the document 
// is encrypted
DocObject docObjectSurveyForm = starDocs.storage.upload(
  "C:\\Documents\\SurveyForm_blank.pdf", "password");

// Form field values
ArrayList<PDFFormFieldFillData> formFields = 
  new ArrayList<PDFFormFieldFillData>();
formFields.add(
  new PDFFormFieldFillData("txtFirstName", "Nikita", true));
formFields.add(
  new PDFFormFieldFillData("radioGender", "radioFemale", true));
formFields.add(
  new PDFFormFieldFillData("listboxLanguages", "Russian,English"));

// Fill form
DocObject docObjectSurveyFormFilled = 
  starDocs.docOperations.fillForm(docObjectBalanceSheet, null, 
    formFields);

// Do something with docObjectSurveyFormFilled
// ...

var
  StarDocs: TgtStarDocsSDK;
  DocObjectSurveyForm: TgtDocObject;
  DocObjectSurveyFormFilled: TgtDocObject;
  FormFields: TObjectList<TgtPDFFormFieldFillData>;
begin
  StarDocs := nil;
  DocObjectSurveyForm := nil;
  DocObjectSurveyFormFilled := nil;
  FormFields := nil;
  try
    // Set up connection details
    StarDocs := TgtStarDocsSDK.Create(nil);
    StarDocs.ConnectionSettings.ApiServerUri :=
      'http://api.gnostice.com/stardocs/v1';
    StarDocs.ConnectionSettings.ApiKey := '<API Key>';
    StarDocs.ConnectionSettings.ApiSecret := '<API Secret>';
    // Force full permissions on PDF files protected 
    // with an permissions/owner/master password
    StarDocs.Preferences.DocPasswordSettings.ForceFullPermission := True;

    // Authenticate
    StarDocs.Auth.loginApp;

    // Upload file, optionally specifying the password if the document 
    // is encrypted
    DocObjectSurveyForm:= StarDocs.Storage.Upload(
      'C:\Documents\SurveyForm_blank.pdf', 'password');

    // Form field values
    FormFields := TObjectList<TgtPDFFormFieldFillData>.Create;
    FormFields.Add(
      TgtPDFFormFieldFillData.Create('txtFirstName', 'Nikita', True));
    FormFields.Add(
      TgtPDFFormFieldFillData.Create('radioFemale', 'Yes', True));
    FormFields.Add(
      TgtPDFFormFieldFillData.Create('listboxLanguages', 'Russian,English'));

    // View file, optionally specifying the password if the document 
    // is encrypted
    DocObjectSurveyFormFilled:= StarDocs.DocOperations.FillForm(
      DocObjectBalanceSheet, nil, FormFields);

    // Do something with DocObjectSurveyFormFilled
    // ...
  finally
    if Assigned(FormFields) then
      FreeAndNil(FormFields);
    if Assigned(DocObjectSurveyForm) then
      FreeAndNil(DocObjectSurveyForm);
    if Assigned(DocObjectSurveyFormFilled) then
      FreeAndNil(DocObjectSurveyFormFilled);
    if Assigned(StarDocs) then
      FreeAndNil(StarDocs);
  end;
end;

The content of the field name and values should match the same as what is exported from the PDF viewer (our HTML5 viewer or any other viewer such as the Adobe Reader) on a "Submit" action via the HTTP GET or POST method. The content is dependent on the field type and its other properties. The following table gives a brief explanation of the same.

Field Type	FieldName Content	FieldValue Content
Text box	Form field mapping name (if present) or form field name	Form field value
Check box		Form Field export value (if present) or form field name of checked box
Radio button		Form Field export value (if present) or form field name of selected radio button item
List box (single select)		Form field export value (if present) or form field display value of selected item
List box (multi select)		Comma separated list of form field export value (if present) or form field display value of selected items
Combo box (single select)		Form field export value (if present) or form field display value of selected item
Combo box (multi select)		Comma separated list of form field export value (if present) or form field display value of selected items