Skip to main content

         This documentation site is for previous versions. Visit our new documentation site for current releases.      

Generating complex PDFs on your UI

Updated on December 4, 2023

Provide your users with tools to import case information to their devices. By configuring an out-of-the-box activity to convert case data to a PDF file, you help users access and archive information that is related to their cases with less effort and at any time.

For example, in a price comparison application, you can configure a button that prints a PDF of the offers that the user selects for comparison.
Note: For simple use cases, you can use the Create PDF shape flow shape. For more information, see Flow shapes.
The pyViewAsPDF activity is a sample of an out-of-the-box solution that you can use to generate a PDF. If you prefer, you can also build a custom activity that matches your business needs and add steps that generate PDF files in the context of that activity. In that scenario, configure the Property-Set-HTML method as described in the following procedure, and then add a step calling the HTMLToPDF activity.
Note: PDF is a restrictive format that forces hard constraints on settings such as margins or layouts. Consequently, the HTMLToPDF rule does not support the conversion of dynamic layout groups. As a best practice, use free form layouts or smart layouts with forms that you want to print to PDF.
  1. In the navigation pane of Dev Studio, click Records.
  2. Expand the Technical category, and then click Activity.
  3. Open the pyViewAsPDF activity.
  4. Create the HTML content from which you want to generate the PDF:
    1. Expand the Property-Set-HTML method.
    2. In the HTMLStream field, enter the name for the HTML fragment on which you want to base the PDF, and then click the Open icon.
      For example: Enter CompareOffersHTML, and then click the Open icon.
    3. In the New tab, click Create and open.
    4. In the HTML Source field, enter the HTML code that you want to use to generate the PDF.
      Note: To use custom CSS, enable CSS use, and then upload the style sheet as a text file. For more information, see Creating PDF files by using a compact style sheet.
  5. Optional: To enable custom fonts in the PDF output, perform the following actions:
    1. Upload the .ttf file of the font that you want to use as a binary file.
      For more information, see Creating binary file rules.
    2. In the HTML Source field, add the custom font reference by using the @font-face rule.
      For example:
                                      @font-face {
                                      font-family: "Mangal";
                                      src: url("webwb/mangal.ttf") format("ttf");

      For more information, see Customizing fonts for your Pega application.

    3. Click Save, and then return to the pyViewAsPDF tab.
  6. Create the name for the output PDF file:
    1. Expand the Property-Set method.
    2. In the Param.PDFName row, in the PropertiesValue field, enter the name of the file in double quotation marks.
      For example: Enter "CompareOffers.pdf"
  7. Optional: To define custom formats for your PDF by using parameters, perform the following actions:
    1. In the step list, click Add a step.
      Note: Ensure that the step precedes the step that contains the call HTMLToPDF activity.
    2. In the new step row, in the Method field, select Property-Set, and then expand the step.
    3. In the PropertiesName field, enter the name of the parameter that you want to adjust.
    4. In the PropertiesValue field, enter the value of the parameter.
      For example: Margins use the following parameter names:

      ParameterDefault value (px)

      For more information on HTMLtoPDF parameters, see HTMLtoPDF parameters.

  8. Click Save.
What to do next: Integrate the activity into your case, for example, by adding it to a control or a utility shape.

Creating PDF files by using a compact style sheet

Applicable to Theme Cosmos applications

Adjust the style of your PDF to the needs of your business by using a custom compact style sheet (CSS).

When you create a PDF file by using the Create PDF smart shape or the HTMLtoPDF activity, the system automatically applies the application skin CSS to the PDF. To change this default setting, enable CSS processing for PDF files, and upload the target CSS file to Pega Platform.

    Creating a text file that holds the custom CSS

  1. In the header of Dev Studio, click CreateTechnicalText File.
  2. On the New tab, define the text file record configuration and context, and then click Create and open.
    The file extension for text files containing CSS is .css.
  3. In the text field, enter the CSS markup.
    You can also upload an existing file by clicking Upload file.
  4. In the upper-right corner of the form, click Save.
  5. Enabling CSS for PDF files

  6. In Dev Studio, search for UseCompactStylesforPDF dynamic system setting, and then click the result that appears in the dialog box.
  7. On the Settings tab, in the Value field, enter true.
  8. Click Save.
What to do next: Add the reference to the CSS file to the HTML markup that you use to generate the PDF. For more information, see Generating complex PDFs on your UI.

HTMLtoPDF parameters

The HTMLtoPDF activity that you use to generate PDFs from your application supports a number of parameters for controlling the look and format of your file.

ParameterPurposeDefault valuePD4ML Specific?
isClearCacheRemoves all objects (images, CSS) from internal PD4ML caches when set to true.

A true setting helps to avoid memory leaks for large TTF and TTC files.

pyDocumentViewModeControls the default document view mode when you open the PDF in a reader. Available values:
  • SinglePage
  • OneColumn
  • TwoColumnLeft
  • TwoColumnRight
  • TwoPageLeft
  • TwoPageRight
    Note: Available in Pega Platform version 8.7.6 or newer.
pyEditablePDFMakes the PDF editable when set to true, which forces PD4ML to convert HTML forms into PDF forms (Acroforms).

When set to true, text fields, checkboxes, and other form elements become editable.

pyEnableOutlinesGenerates outlines or bookmarks in the PDF document when set to true.

You can generate outlines from anchor tags. For example: <a name="Bookmark1">.

pyEnableSmartTableBreaksEnables PD4ML insertion of page breaks in between table rows to make the table portions fit the page height when set to true.

If the table has a header, a true setting replicates the header row in each table section.

pyGenerateToolTipsProduces tooltips from TITLE HTML attributes (PDF Annotations) when set to true.falseYes
pyHTMLDisableProcessingDisables processing the HTML input for conformance when set to true.

The application processes the HTML stream and invokes the HTML TIDY utility to get a clean stream of the HTML input.

pyMarginLeft, pyMarginRight, pyMarginTop, pyMarginBottomDefines custom margins in pixels for each side of the PDF.emptyNo
pyPDFEmbedFontEnables the system to embed the fonts into the PDF document from pyPDFFontsDirectory when set to true.falseYes
pyPDFEnableHyperlinksEnables hyperlinks in the PDF document when set to true. When set to false, hyperlinks are not actionable.falseYes
pyPDFFontsDirectorySpecifies the path to the directory with font files.emptyYes
pyPDFFooterHTMLTemplateDefines the HTML code for the page footer. For example:
<div style="color:blue;"> 
page $[ page] of total $[total] </div>
pyPDFGeneratePDFAForces PD4ML to output a PDF compliant with the PDF/A specification for long-term archiving.

This method call does not guarantee that the generated output complies with the PDF/A format if embedding of fonts is not set to true.

Request the last rendering status to check if the generated PDF document is PDF/A compliant.

pyPDFHeaderHTMLTemplateDefines the HTML code for the page header. For example:
<div style="color:blue;"> 
page $[ page] of total $[total] </div>
pyPDFPageOrientationSets the page orientation of the PDF document. Available values are Landscape or Portrait.LandscapeYes
pyPDFPageSizeSets the page size of the PDF document.A4Yes
pyPDFPropsDirectorySpecifies the directory to use at run time to generate the Properties file during PDF generation.emptyYes
pyShowWarningShows the log warning during HTML TIDY parsing when set to true.

HTML TIDY errors are always shown.

startPageSets the page number counter to a specified value for page numbering in document headers and footers.1Yes
timeoutForExternalContentSets the timeout in milliseconds to fetch external images.

If your PDF content includes external images, the application must send a request to fetch them. You can set a timeout to prevent this operation from delaying PDF generation.

-1 (infinite)No

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best. is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us