Home » Newsletter » November 2017

by Santosh Patil

UniGUI is a web-application development framework for Delphi. Gnostice now provides a native UniGUI component to easily add a multi-format document viewer to your web-application. The viewer supports PDF form filling and offers forms API, and events which enable an enriched form filling user experience. In this article we will look at the steps to be followed to add the viewer to your web application.

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. At a minimum please follow the getting started article to download and install the StarDocs SDK for Delphi.

This article uses the Delphi 10.2 Tokyo IDE with UniGUI version 1.0.0.1416. However you should be able to follow it for earlier versions of Delphi as well down to Delphi XE7 (StarDocs SDK is supported only from XE7 onward).

You can download the test PDF file used in this demo from here.

A demo project based on this article is available for download from here. Unzip the file and follow the instructions in the Readme.txt file to build and run it.

1. In the IDE choose File > New > Other. In the dialog that opens choose Delphi Projects > uniGUI for Delphi > Application Wizard and click OK.
2. In the uniGUI Application Wizard dialog choose Project Type as Standalone Server, type in project name (say UniDocumentViewer) and click OK.
3. If a popup asks about enabling "Visual Component Library" then click Yes.
4. Open the design view of Main.pas. Place the following controls on the form: TUniButton, TgtStarDocsSDK, TgtUniStarDocsViewer, and TUniMemo.
5. Change the caption of UniButton1 to "Load". Appropriately size, position and align the controls to match the screenshot shown below.

6. Anchor UniButton1 to Top, Left. Anchor gtUniStarDocsViewer1 to all sides. Anchor UniMemo1 to Left, Right and Bottom.
7. Click on gtStarDocsSDK1 component and fill in the StarDocs server connection details in the object inspector (under ConnectionSettings). You can also modify the viewer settings if you wish (under Preferences -> Viewer).
8. Click on gtUniStarDocsViewer1 component and fill in the StarDocsSDK property with gtStarDocsSDK1.

9. Let's load the PDF document into the viewer when the "Load" button is clicked. (Note: For this demo to work correctly you need to download and use the PDF file from here. This is because we reference the form fields using their "name" attribute.) Add an OnClick event handler for UniButton1 with the following code.

procedure TMainForm.UniButton1Click(Sender: TObject);
begin
  gtUniStarDocsViewer1.Load('C:\docs\SimpleForm.pdf');
end;

10. Let's subscribe to few events fired from the viewer and log them in the memo field. This will help us understand the types of events and what user interactions cause them to be fired. Click on the gtUniStarDocsViewer1 component and go to the Object Inspector -> Events tab and add handlers for some of the events. See screenshot below which shows the events which are handled. The event handler code is shown below the screenshot.


type
  TMainForm = class(TUniForm)
  ...
  private
    procedure AddMessage(Msg: String);
  ...
end;

// Utility method to format and prepend a message to the memo field
procedure TMainForm.AddMessage(Msg: String);
begin
  UniMemo1.Text := Msg + ' | ' + UniMemo1.Text;
end;

procedure TMainForm.gtUniStarDocsViewer1FormFieldChanged(ASender: TObject;
  AFormField: TgtPDFFormField);
begin
  AddMessage('OnFormFieldChanged: [' + AFormField.FullyQualifiedName + ']');
end;

procedure TMainForm.gtUniStarDocsViewer1FormFieldClicked(ASender: TObject;
  AFormField: TgtPDFFormField);
begin
  AddMessage('OnFormFieldClicked: [' + AFormField.FullyQualifiedName + ']');
end;

procedure TMainForm.gtUniStarDocsViewer1FormFieldEnter(ASender: TObject;
  AFormField: TgtPDFFormField);
begin
  AddMessage('OnFormFieldEnter: [' + AFormField.FullyQualifiedName + ']');
end;

procedure TMainForm.gtUniStarDocsViewer1FormFieldExit(ASender: TObject;
  AFormField: TgtPDFFormField);
begin
  AddMessage('OnFormFieldExit: [' + AFormField.FullyQualifiedName + ']');
end;

procedure TMainForm.gtUniStarDocsViewer1FormLoaded(Sender: TObject);
begin
  AddMessage('OnFormLoaded');
end;

procedure TMainForm.gtUniStarDocsViewer1FormModified(Sender: TObject);
begin
  AddMessage('OnFormModified');
end;

11. Let's run the app now and try it out. After the main page loads click on the "Load" button to load the PDF form. Once the form loads you can interact with it and see the events that are logged in the memo field. The screenshot below shows one such interaction.

12. Now let's take some action in the event handlers. Let's show a popup when the "Help" button is pressed. Here is the code for the event handler to do this.

procedure TMainForm.gtUniStarDocsViewer1FormFieldClicked(ASender: TObject;
  AFormField: TgtPDFFormField);
begin
  AddMessage('OnFormFieldClicked: [' + AFormField.FullyQualifiedName + ']');
  if (AFormField.FullyQualifiedName = 'HelpButton') then
  begin
    showMessage('You clicked the ''Help'' button.<br>'
      + 'This popup is being shown in response to the ''onFormFieldClick'' event.');
  end;
end;

13. Let's also make it easy for the user to fill out the "Country" field by showing a lookup popup so they can select the country rather than type it. We'll show this popup when the user focuses on the "Country" field. For this we need to add a new form. Click on the main project in the Project Manager then on the main menu select File -> New -> Other... Under "uniGUI for Delphi" select Form and click OK. Select the Form Type as Application Form.
14. For UniForm1 set the caption as "Select Country". Remove the BorderIcons for Minimize and Maximize. Add a TUniListBox to list the countries, and populate it with a few country names. Also add a TUniButton and change its caption to "OK" and set its ModalResult set to "mrOk". Finally your form would like the one shown in the screenshot below.

15. Let's add an OnClick event handler to the "OK" button in which we'll set the "Country" field to the value selected by the user. The code for this is shown below.

procedure TUniForm1.UniButton1Click(Sender: TObject);
var
  SelectedCountry: String;
begin
  if (UniListBox1.ItemIndex <> -1) then
  begin
    SelectedCountry := UniListBox1.Items[UniListBox1.ItemIndex];
    // Call Forms API to set the value to the text field
    FTextFormField.SetValueAsString(SelectedCountry);
  end;
end;

16. We'll also add a helper method to show the popup and pass in the FTextFormField property from the main form. Add the following code to the newly created TUniForm1.

uses gtxUniStarDocsViewer;

type
  TUniForm1 = class(TUniForm)
    ...
  private
    FTextFormField: TgtViewerPDFTextFormField;
  public
    procedure ShowPopup(AFormField: TgtViewerPDFTextFormField);
  end;

procedure TUniForm1.ShowPopup(AFormField: TgtViewerPDFTextFormField);
begin
  FTextFormField := AFormField;
  Self.ShowModal();
end;

17. We need to show the new form that we just added when the "Country" field receives user focus. For this modify the OnFormFieldEnter handler as shown below.

uses Unit1;

procedure TMainForm.gtUniStarDocsViewer1FormFieldEnter(ASender: TObject;
  AFormField: TgtPDFFormField);
begin
  AddMessage('OnFormFieldEnter: [' + AFormField.FullyQualifiedName + ']');
  if (AFormField.FullyQualifiedName = 'Country') then
  begin
    UniForm1.ShowPopup(AFormField as TgtViewerPDFTextFormField);
  end;
end;

18. Finally let's add a popup that displays all the form field values when the user clicks the "Submit" button, and a handler to reset the form fields when the user clicks the "Reset" button. For this modify the OnFormFieldClicked handler and add some supporting code as shown below.

uses System.Generics.Collections;

type
  TMainForm = class(TUniForm)
    ...
  private
    ...
    procedure GetAllFormFieldsCallBack(AFormFields: TList<TgtPDFFormField>);
  end;

procedure TMainForm.gtUniStarDocsViewer1FormFieldClicked(ASender: TObject;
  AFormField: TgtPDFFormField);
begin
  AddMessage('OnFormFieldClicked: [' + AFormField.FullyQualifiedName + ']');
  if (AFormField.FullyQualifiedName = 'HelpButton') then
  begin
    showMessage('You clicked the ''Help'' button.<br>'
                + 'This popup is being shown in response to the ''onFormFieldClick'' event.');
  end
  Else if (AFormField.FullyQualifiedName = 'SubmitButton') then
  begin
    // Call async method to get all the form fields. Once the form fields are 
    // fetched the callback procedure 'GetAllFormFieldsCallBack' will be called
    gtUniStarDocsViewer1.Forms.GetAllFormFields(GetAllFormFieldsCallBack);
  end
  Else if (AFormField.FullyQualifiedName = 'ResetButton') then
  begin
    showMessage('You clicked the ''Reset'' button.<br>'
                + 'Using the Forms API we have reset the form.');
    gtUniStarDocsViewer1.Forms.ResetForm();
  end;
end;

procedure TMainForm.GetAllFormFieldsCallBack(AFormFields: TList<TgtPDFFormField>);
var
  Index: Integer;
  FormField: TgtPDFFormField;
  MsgStr: String;
begin
  // Need to take ownership of AFormFields
  MsgStr := '';
  try
    // Loop through all the form fields and build a message to show to user
    for Index := 0 to (AFormFields.Count - 1) do
    begin
      FormField := AFormFields.Items[Index];
      if FormField is TgtViewerPDFTextFormField then
      begin
        MsgStr := MsgStr + FormField.FullyQualifiedName + ': ';
        MsgStr := MsgStr + (FormField as TgtViewerPDFTextFormField).Value;
        MsgStr := MsgStr + '<br>';
      end;
    end;
    showMessage('You clicked the ''Submit'' button.<br>'
                + 'Here are the values entered in the form:<br>' + MsgStr);
  finally
    AFormFields.Free;
  end;
end;

Many of the Forms API are asynchronous because after the server-side call is made the client side JavaScript needs to communicate with the viewer iframe and this communication is essentially an asynchronous, message-based one. Therefore all the asynchronous methods take a callback procedure which is invoked once the viewer iframe responds back with the requested data. Finally we are ready to run the app and try it out. The screenshot below shows the lookup form being shown when the "Country" field gets focus.