XtremeDocumentStudio
.NET
PDFOne
.NET
XtremeDocumentStudio
(for Java)
PDFOne
(for Java)
XtremeDocumentStudio
Delphi
eDocEngine
VCL
PDFtoolkit
VCL
StarDocs
Web APIs

Using StarDocs with UniGUI

Easily add a multi-format document viewer to your Delphi UniGUI web app
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.
  10. procedure TMainForm.UniButton1Click(Sender: TObject);
    begin
      gtUniStarDocsViewer1.Load('C:\docs\SimpleForm.pdf');
    end;
    
  11. 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.
  12. 
    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;
    
  13. 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.
  14. 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.
  15. 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;
    
  16. 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.
  17. 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.
  18. 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.
  19. 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;
    
  20. 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.
  21. 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;
    
  22. 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.
  23. 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;
    
  24. 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.
  25. 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.

---o0O0o---

Our .NET Developer Tools
XtremeDocumentStudio .NET

Multi-format document-processing component suite for .NET developers.

PDFOne .NET

A .NET PDF component suite to create, edit, view, print, reorganize, encrypt, annotate, and bookmark PDF documents in .NET applications.

Our Delphi/C++Builder developer tools
XtremeDocumentStudio Delphi

Multi-format document-processing component suite for Delphi/C++Builder developers, covering both VCL and FireMonkey platforms.

eDocEngine VCL

A Delphi/C++Builder component suite for creating documents in over 20 formats and also export reports from popular Delphi reporting tools.

PDFtoolkit VCL

A Delphi/C++Builder component suite to edit, enhance, view, print, merge, split, encrypt, annotate, and bookmark PDF documents.

Our Java developer tools
XtremeDocumentStudio (for Java)

Multi-format document-processing component suite for Java developers.

PDFOne (for Java)

A Java PDF component suite to create, edit, view, print, reorganize, encrypt, annotate, bookmark PDF documents in Java applications.

Our Platform-Agnostic Cloud and On-Premises APIs
StarDocs

Cloud-hosted and On-Premises REST-based document-processing and document-viewing APIs

Privacy | Legal | Feedback | Newsletter | Blog | Resellers © 2002-2017 Gnostice Information Technologies Private Limited. All rights reserved.