Page Comparison

...

Luckily, we’ve run into many of the issues ourselves and can provide some guidance to help you get your PDFs looking sharp.

Headers and Footers

iOS

When running on iOS Pulsar utilizes UIPrintPageRenderer to generate PDFs. Pulsar requires you to specify a node in the document that will represent your header. To do this, specify headernode in your saveAs request. This header will be printed at the top of each page. It’s important to note that you are responsible for ensuring that either the header is not included inside the docnode or that it is hidden from view.

When specifying a headernode you must also calculate and include the height in points for the header. We have done this in our own code by programmatically inspecting the scrollheight of the outermost node of the header. Once calculated, include headerheight specified as an integer inside the printoptions of the saveAs request.

It is also important to note that any styles necessary for the header should be done inline. We’d like to enable custom css for headers and footers, but that is a future improvement. One way that we at Luminix have addressed this issue is to programmatically move our header and footer into iFrames and then supply the iFrame as the headernode/footernode. In doing this we are able to add CSS in the head tag of the iFrames.

It should also be noted that iOS will draw page numbers on the footer by default.

Windows

Windows follows the same https://github.com/luminixinc/PulsarForSalesforceAdvancedJSExamples

A Complete Example

We have developed a ready-to-use example of how a PDF might be generated and saved across all three platforms. The example is documented to explain what is going on at various stages and broken up using the Strategy Pattern to handle the differences between each platform.

Contained in the repository in the example-report folder is the example-report.pulsarapp which you can upload as a File to your Salesforce organization to see this in action while running the Pulsar for Salesforce App. Simply open the .pulsarapp from the Content Library.

The Complexity

Generating PDFs from HTML content is a complex procedure that is often achieved through online services or through the use of enterprise software. So please keep in mind that although this seems like it should be a simple task, comprehensive conversion from the browser while offline is not something to be taken for granted! For comprehensive notes on these differences, please explore the strategies and htmlFragments for each platform in the example-report.

When running on iOS Pulsar utilizes UIPrintPageRenderer to generate PDFs. While this is a very useful tool, it has a number of confusing nuances that are addressed in the iOS strategy in our example-report. Many of these relate to identifying the header and footer regions and calculating their height. Page numbers however are provided by default and located in the footer.

Windows follows the same general format as iOS but it utilizes IronPDF. Windows requires you to add your own page numbers in the HTML. IronPDF gives you access to handlebars type variables like:

{page} {total-pages} {url} {date} {time} {html-title} & {pdf-title}

When specifying your headerheight/footerheight on Windows you should pass 0 and instead include the height of the header and footer in the topmargin/bottommargin values. The JSAPI provides a method to get the platform type. (These changes are present in Pulsar FSL versions after August 15th.)

Android

For Android, Pulsar makes use of the native Chrome browser present on Android devices in order to render PDFs. This is achieved in a completely different way and we recommend that you have different HTML templates for handling Android and iOS/Windows.

Android makes use of table structure to do repeating headers and footers.

Code Block

<table id="droid-table">
  <thead id="sr-header-droid">
    <!-- Your header goes here -->
    <tr>
      <th> ... </th>
    </tr>
  </thead>

  <div id="sr-footer-droid" style="display: table-footer-group; width: 100%; bottom: 0; position: fixed;">
    <!-- Your footer goes here, not that this is not a tfoot div and requires special styling -->
  </div>

  <tbody id="sr-body-droid" *ngIf="subTemplate.body() as body">
    <!-- Your document body goes here, it can be many rows -->
    <tr>
      <td>...</td>
    </tr>
  </tbody>
</table>

This pathway needs more testing but should work.

Using HTML/JS Tables:

If you need to generate a PDF offline from your HTML/JS app, we've determined that the best approach is to avoid the use of <table> elements and instead build the page structure with <div> elements. It's been noted (https://stackoverflow.com/questions/9288802/avoid-page-break-inside-row-of-table/27209406) that <tr> elements do not appear to respect the break-inside/page-break-inside CSS attributes. Note: If you are building your app to run within Pulsar FSLapp: Pulsar FSL app is utilizing Bootstrap 4. In the discussions around page breaks and <table> elements, it's been suggested that Bootstrap may impact this.

There are a number of suggested solutions in the Stack Overflow post. We have tested a few of the simpler ones (changing the attribute to break-inside and applying the properties to <td> elements instead of <tr>) without success. So we think using <div> elements as the primary structure of the document will be the easiest path forward.

Additional Notes

Images and Canvas:

Using images, canvas elements and fonts will work in your custom HTML implementations, but it is possible to run into issues when attempting to generate PDF files, due to CORS rules or similar access restrictions imposed by the webview environment. Our recommendation is to convert each of these resources to a 'data URI' format with Base64 encoding.

...

Font files may require pre-deployment processing to avoid issues loading during PDF generation or printing. Embedding Fonts as base64 data urls works best, as this can be inlined or added directly to precompiled framework CSS for inclusion in your HTML/JS.

Note: On Windows, custom font files are sometimes needed to avoid issues with PDF rendering, as the PDF rendering engine environment only has access to a limited set of fonts, and these are not guaranteed to match the operating system installed fonts. In these cases, fonts can be included using @font-face CSS declarations and relative urls to your fonts, which should be included alongside your HTML/JS resources, for example: