Purpose and Design Considerations:

Previewing PDF documents directly within a Constellation UI application empowers users to review important files without leaving the workflow or downloading attachments. This feature can be implemented either by embedding the PDF viewer within a form or by providing access through a clickable link. By integrating document preview into the application, teams can streamline processes such as approvals, compliance checks, and collaborative reviews, resulting in improved workflow efficiency and better user experience.

Note: The ability to preview PDFs within Constellation UI is an extension to the standard user interface, not a default feature. For more details, please see Constellation UI Options

Platform Version: The implementation steps described below are based on Pega Infinity 24.2. Platform features and UI components may evolve, so always verify compatibility with your current version.

Prerequisites:

Import the “Display PDF” Constellation UI gallery component into your application. This component provides the necessary functionality to render PDF files within the UI.

Reference link for DX Component: https://pegasystems.github.io/constellation-ui-gallery/?path=/docs/fields-display-pdf--docs

Note: DX components in the UI gallery as not part of the OOTB design system and an open-source project. The complete ownership of these components lies with the client. For more details see Supporting and Contributing.

Implementation:

Method 1 : Display PDF Directly in a form view

Step 1: Create a form view

Begin by creating a new Form View in your Constellation UI application. This view will serve as the container for displaying the PDF content. This step sets the foundation for embedding the PDF viewer component and allows you to control the layout and user experience from the start.

Step 2: Add a text (single line) property to the view.

Add a new property of type 'Text (Single Line)' to the Form View. This property will hold the base64-encoded PDF content. It is important to use a single line text field to ensure compatibility with the 'Display PDF' configuration. This property acts as the bridge between your data and the PDF viewer, so make sure it is mapped correctly in your data model.

Step 3: Open the field configuration and select “Display PDF” in the “Display as” dropdown.

Access the field configuration settings for the newly added text property. In the 'Display as' dropdown menu, select 'Display PDF'. This setting enables the field to render PDF content directly within the view. Make sure to save the configuration after making this change.

Step 4: Save the configuration.

After configuring the field to display PDF, save the changes to ensure the settings are applied. This step is crucial for the PDF viewer to function correctly within the Form View.

Step 5: Pass PDF Content to the Preview Field:

Before rendering the view, pass the base64-encoded PDF stream to the text field. This can be done in the pre-processing activity of the view. If the PDF is a binary file, use 'pyFileSource'. For attachments of type 'Data-WorkAttach-File', use 'pyAttachStream'. This step ensures that the PDF content is available for rendering and that the viewer displays the correct document.

(Example use case where a stream is generated using HTMLtoPDF activity is demonstrated at the end.)

Step 6: The PDF will now be rendered in the form of view.

Once the base64 stream is passed to the text field, the PDF will be rendered directly within the Form View. Users can view the document without downloading it, enhancing the user experience and workflow efficiency.

Method 2 : Preview PDF on click of a link(Partial view)

Step 1: Create a Partial View

Start by creating a Partial View in your Constellation UI application. This view will be used to display the PDF preview as a clickable link rather than embedding it directly. Partial Views are useful when you want to keep the main form uncluttered and provide optional document previews.

Step 2: Follow Steps 2 – 6 as in Method 1.

Repeat the configuration steps from Method 1, including adding a text (single line) property, setting its display type to 'Display PDF', and passing the base64-encoded PDF stream to the field. However, instead of embedding the field in a form view, place it in the Partial View. This will render the PDF preview as a clickable link, allowing users to open the document in a separate view. This approach is ideal for scenarios where document preview is optional or secondary to the main workflow.

 

Additional Configuration:

You can customize the PDF viewer by configuring its width, height, and toolbar settings in the field configuration. These options help tailor the viewer to your application's layout and user preferences, ensuring a consistent and user-friendly experience.

 

Use Case : Editable PDF Content with Dynamic Preview

A scenario where PDF content needs to be displayed to the user. The user can edit the content and then preview the PDF with the edited content by clicking a link

Step 1: Configure a form view with a rich text editor

Create a Form View that includes a rich text editor where users can input or edit the content that will be converted into a PDF. This editor allows for dynamic content creation and sets the stage for generating preview of a  PDF. Make sure the editor is linked to a property that stores the content for further processing.

Step 2: Add a partial view for PDF Preview

Add a Partial View to the form that contains the preview text field configured to display as 'Display PDF'. This setup separates the editing interface from the preview interface, improving usability and clarity for the user.

Step 3: In the pre-processing of this view, set the PDF content and initial preview for the PDF

Step 3.1: Use a correspondence rule for the PDF content

Define a correspondence rule that contains the template or structure of the PDF content. This rule will be used to generate the actual PDF stream based on the user's input, ensuring consistency and proper formatting.

Step 3.2: Create a pre-processing activity

Develop a pre-processing activity that sets the PDF content and converts it into a base64 stream. Pass this stream to the preview field in the Partial View. This ensures that the initial preview is available when the form is rendered, providing immediate feedback to the user.

Step 4: Configure Form Refresh Settings

In the flow action's form refresh settings, configure the system to update the preview when the PDF content changes. This dynamic refresh ensures that users always see the latest version of the document, enhancing interactivity and accuracy.

Step 4.1: Execute a data transform

Create a data transform that triggers when the PDF content property changes. This transform will prepare the updated content for preview, ensuring the preview field always reflects the most recent edits.

Step 4.2: Call an Activity to Update the PDF Stream

Within the data transform, call an activity that regenerates the base64 stream of the updated PDF content. This activity should follow the same logic as the pre-processing activity but skip the initial content setting step, focusing only on updating the stream.

Step 5: Run a case and test the functionality

Execute a case to validate the implementation. Initially, verify that the PDF preview displays the correct content. Then, modify the content in the rich text editor and confirm that the preview updates accordingly when the link is clicked. This step ensures the dynamic update mechanism works as intended.

Step 5.1: Initial preview

Ensure that the initial PDF content is correctly rendered in the Partial View when the form loads, providing immediate feedback to the user.

On click of preview:

Step 5.2: Change content and preview

Edit the content in the rich text editor and click the preview link. Verify that the updated content is reflected in the PDF viewer, confirming that the dynamic update mechanism works as intended.

Additional Info: Directly Viewing the PDF in a Form View (Instead of a Clickable Link)

In some workflows, it’s preferable for users to see the PDF document immediately within the main interface, rather than having to click a link to open a preview. This approach is especially useful when document review is a core part of the process, such as in approval flows, compliance checks, or when users need to reference the PDF while filling out other fields.

Implementation steps:

Add the Text Field Property Directly in the Form View:

• Instead of placing the PDF preview field in a partial view (which creates a clickable link), embed the text field property configured for PDF to display directly within the main form view.
• This ensures the PDF is rendered as soon as the form loads, providing instant access and visibility.

 

Constellation 101 Series

Enjoyed this article? See more similar articles in Constellation 101 series.