generate-pdf

The generate-pdf action allows you to quickly create a PDF file version of HTML content, whether a receipt, report, form, or other document.

The URI of the generated file is returned and is available as part of the action instance output. When you tap the button, the app compiles the necessary information and generates a file you can save or share instantly.

Configuration options

Some properties are common to all actions, see Common action properties for the list of actions and their configuration options.

Core structure

html

Use standard HTML elements to ensure optimal formatting and compatibility when rendering content in the PDF file, for example, <html><body>Invoices are provided monthly.</body</html>. The HTML can be built up using JSONata or JavaScript.

fileName

Give the PDF a name, this name is used as the local file name, and is referenced as part of the uri, which can be accessed via the action's instance output (=@ctx.actions.generatePDF.outputs.uri). The .pdf extension is automatically added to the fileName.

title

Provide the action button with a title, for example, Invoice.

Other options

icon

Select an icon to display when the action is configured as the secondary button or in a jig-header.

isHidden

true hides the action button. false shows the action button. The default is false.

page

Controls the PDF page size, orientation, custom dimensions, and margins. See Page options for more information.

styles

isDanger - Styles the action button in red or your brand's designated danger color.
isDisabled - Displays the action button as greyed out.
isPrimary - Styles the action button in blue or your brand's designated primary color.
isSecondary - Sets the action as a secondary button, accessible via the ellipsis. The icon property can be used when the action button is displayed as a secondary button.

Page options

Use page to control the physical PDF page layout.

actions:
  - children:
      - type: action.generate-pdf
        options:
          html: =@ctx.datasources.template.html
          fileName: report
          page:
            size: letter
            orientation: portrait
            margin: none

Supported page fields:

size — letter, legal, tabloid, a4, or a3
orientation — portrait or landscape
width and height — custom page size in PDF points
margin — none, a single number, or an object with top, right, bottom, and left

Named page sizes use PDF points. 72pt = 1in.

letter — 612 × 792
legal — 612 × 1008
tabloid — 792 × 1224
a4 — 595 × 842
a3 — 842 × 1191

If you do not set page, the PDF uses letter and portrait by default.

If you set both width and height, they take priority over size and orientation.

Margin options

margin supports three formats:

none — no margin
number — the same margin on all sides
object — a different margin for each side, specified separately

Omitted margin sides default to 0.

Examples:

page:
  size: a4
  margin: 36

page:
  size: letter
  orientation: landscape
  margin:
    top: 36
    right: 48
    bottom: 36
    left: 48

Page size and HTML layout

The YAML page configuration sets the physical PDF page size.

CSS @page size rules do not change the PDF page size. They affect only the layout inside the fixed page.

To avoid overflow or extra whitespace, keep your HTML and CSS aligned with the YAML page settings.

@page { size: letter landscape; margin: 0; }
body  { width: 792pt; height: 612pt; }

If the YAML and CSS sizes do not match, the PDF still uses the YAML size.

Multi-page rendering

Multi-page HTML paginates correctly on iOS.

Page breaks in your HTML and CSS are honored across physical PDF pages. For example, CSS break-after: page now places content on separate PDF pages.

Considerations

You can reference the local PDF file using the action's output uri in other actions or components, =@ctx.actions.generatePDF.outputs.uri. For example, generate the PDF file, then share the file.
Depending on where you save and use the saved PDF, you might need to use conversions.
The .pdf extension is automatically added to the fileName.
The page margin is applied by the PDF generator. It is not injected into the HTML as CSS.
Do not also set @page { margin: ... } in your HTML when you use the YAML page.margin field. This avoids double spacing.
When you use custom dimensions, both width and height must be greater than 0.

Examples and code snippets

In this example, an action list contains two actions: the first generates a PDF of a checklist, the second shares the PDF via a messaging app on the device.

Example: See the full code sample in GitHub.

title: Site Checklist
type: jig.document
  
source:
  documentType: HTML
  # Use a datasource with the required raw HTML
  content: =@ctx.datasources.html-data.checklist-html
# Create an action list that will first create the PDF from the HTML,
# secondly share the pdf file via one of the devices messaging apps.          
actions:
  - children:
      - type: action.action-list
        options:
          title: Send checklist
          isSequential: true
          actions:
            # First action to create the pdf.
            - type: action.generate-pdf
              # Add an instanceId to use in the actions output expression.
              instanceId: share-pdf
              options: 
                # Provide the HTML of the checklist.  
                html: =@ctx.datasources.html-data.checklist-html
                # Provide the name of the pdf
                fileName: foreman-checklist
            # Add the second action to share out the pdf,
            # on one of the devices messaging apps.    
            - type: action.share
              options: 
                message: Completed morning checks on Site B
                subject: Site checks complete
                # Use the action instance output to reference the file.
                fileUri: =@ctx.actions.share-pdf.outputs.uri

# Use a datasource with the required HTML
datasources:
    html-data:
      type: datasource.static
      options:
        data:
          - id: 1
            checklist-html: |
              <!DOCTYPE html>
                <html lang="en">
                <head>
                    <meta charset="UTF-8">
                    <meta name="viewport" content="width=device-width, initial-scale=1.0">
                    <title>Construction Site Checklist</title>
                    <style>
                        body {
                            font-family: Arial, sans-serif;
                            margin: 20px;
                            padding: 20px;
                            background-color: #f4f4f4;
                        }
                        .checklist {
                            background: #fff;
                            padding: 20px;
                            border-radius: 5px;
                            box-shadow: 0 0 10px rgba(0, 0, 0, 0.1);
                        }
                        h2 {
                            text-align: center;
                        }
                        ul {
                            list-style: none;
                            padding: 0;
                        }
                        li {
                            margin: 10px 0;
                        }
                        input[type="checkbox"] {
                            margin-right: 10px;
                        }
                    </style>
                </head>
                <body>
                    <div class="checklist">
                        <h2>Construction Site Checklist</h2>
                        <ul>
                            <li><input type="checkbox"> Safety gear checked (helmets, vests, gloves, etc.)</li>
                            <li><input type="checkbox"> Equipment inspected and functional</li>
                            <li><input type="checkbox"> Site hazards identified and secured</li>
                            <li><input type="checkbox"> Workers briefed on tasks and safety</li>
                            <li><input type="checkbox"> Materials delivered and accounted for</li>
                            <li><input type="checkbox"> Work permits and documentation verified</li>
                            <li><input type="checkbox"> Emergency procedures reviewed</li>
                            <li><input type="checkbox"> Waste disposal managed</li>
                            <li><input type="checkbox"> Final site walk-through completed</li>
                        </ul>
                    </div>
                </body>
                </html>

Control page size, orientation, and margins

Use page when the PDF must match a specific paper size or layout.

actions:
  - children:
      - type: action.generate-pdf
        options:
          title: Export report
          html: =@ctx.datasources.report.html
          fileName: operations-report
          page:
            size: letter
            orientation: landscape
            margin: none

actions:
  - children:
      - type: action.generate-pdf
        options:
          title: Export report
          html: =@ctx.datasources.report.html
          fileName: operations-report
          page:
            size: a4
            orientation: portrait
            margin: 36

actions:
  - children:
      - type: action.generate-pdf
        options:
          title: Export card
          html: =@ctx.datasources.card.html
          fileName: summary-card
          page:
            width: 360
            height: 504

actions:
  - children:
      - type: action.generate-pdf
        options:
          title: Export report
          html: =@ctx.datasources.report.html
          fileName: operations-report
          page:
            size: letter
            orientation: landscape
            margin:
              top: 36
              right: 48
              bottom: 36
              left: 48

Multi-page HTML example

Use HTML page breaks when the PDF should span multiple pages.

generate-pdf-multi-page.jigx

actions:
  - children:
      - type: action.generate-pdf
        options:
          title: Export slides
          fileName: presentation
          page:
            size: a4
            orientation: portrait
            margin: none
          html: |
            <!DOCTYPE html>
            <html lang="en">
              <head>
                <meta charset="UTF-8">
                <style>
                  @page { size: a4 portrait; margin: 0; }
                  body { margin: 0; }
                  .slide {
                    width: 595pt;
                    height: 842pt;
                    break-after: page;
                  }
                </style>
              </head>
              <body>
                <section class="slide">Page 1</section>
                <section class="slide">Page 2</section>
                <section class="slide">Page 3</section>
              </body>
            </html>

In this example, an action list contains three actions: the first generates a PDF for an invoice, the second saves it to the database, and the third shares the PDF via a messaging app on the device. When saving the file to the database the file is converted from local-uri to data-uri for storage.

Example: See the full code sample in GitHub.

action-generate-pdf-save-share.jigx

title: Monthly invoicing
description: Provide you details
type: jig.default

header:
  type: component.jig-header
  options:
    height: small
    children: 
      type: component.image
      options:
        source:
          uri: https://images.unsplash.com/photo-1450101499163-c8848c66ca85?w=900&auto=format&fit=crop&q=60&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxzZWFyY2h8MTR8fGludm9pY2luZ3xlbnwwfHwwfHx8MA%3D%3D    
  
children:
  - type: component.section
    options:
      title: Details
      children: 
        - type: component.form
          instanceId: inputValues
          options:
            children:
              - type: component.text-field
                instanceId: firstName
                options:
                  initialValue: John Smith
                  label: First name
                  isRequired: false
              - type: component.email-field
                instanceId: email
                options:
                  initialValue: john.smith@global.com
                  label: Email address
              - type: component.number-field
                instanceId: phoneNumber
                options:
                  initialValue: 23445634556
                  label: Mobile number
# Create an action list that will first create the PDF from the HTML,
# secondly save the PDF file to the dynamic database,
# thirdly share the pdf file via one of the devices messaging apps.                  
actions:
  - children:
      - type: action.action-list
        options:
          title: Send Invoice
          isSequential: true
          actions:
           # First action to generate the pdf.
            - type: action.generate-pdf
              instanceId: generate-pdf-id
              options:
                # Provide the HTML for the PDF file.
                html: |
                  <!DOCTYPE html>
                    <html lang="en">
                    <head>
                      <meta charset="UTF-8">
                      <meta name="viewport" content="width=device-width, initial-scale=1.0">
                      <title>Invoice</title>
                      <style>
                        body {
                          font-family: 'Arial', sans-serif;
                          margin: 0;
                          padding: 20px;
                          background-color: #f6f6f6;
                        }
                        .invoice-box {
                          max-width: 800px;
                          margin: auto;
                          padding: 30px;
                          border: 1px solid #eee;
                          box-shadow: 0 0 10px rgba(0, 0, 0, 0.15);
                          background-color: #fff;
                          color: #555;
                        }
                        .invoice-box table {
                          width: 100%;
                          line-height: 1.6;
                          text-align: left;
                          border-collapse: collapse;
                        }
                        .invoice-box table td {
                          padding: 5px;
                          vertical-align: top;
                        }
                        .invoice-box table tr td:nth-child(2) {
                          text-align: right;
                        }
                        .invoice-box table tr.top table td {
                          padding-bottom: 20px;
                        }
                        .invoice-box table tr.information table td {
                          padding-bottom: 40px;
                        }
                        .invoice-box table tr.heading td {
                          background: #eee;
                          border-bottom: 1px solid #ddd;
                          font-weight: bold;
                        }
                        .invoice-box table tr.details td {
                          padding-bottom: 20px;
                        }
                        .invoice-box table tr.item td {
                          border-bottom: 1px solid #eee;
                        }
                        .invoice-box table tr.item.last td {
                          border-bottom: none;
                        }
                        .invoice-box table tr.total td:nth-child(2) {
                          border-top: 2px solid #eee;
                          font-weight: bold;
                        }
                        h2, h3 {
                          margin: 0;
                        }
                      </style>
                    </head>
                    <body>
                      <div class="invoice-box">
                        <table cellpadding="0" cellspacing="0">
                          <!-- Invoice Header -->
                          <tr class="top">
                            <td colspan="2">
                              <table>
                                <tr>
                                  <td class="title">
                                    <h2>Company Name</h2>
                                  </td>
                                  <td>
                                    Invoice #: 12345<br>
                                    Created: January 1, 2025<br>
                                    Due: January 31, 2025
                                  </td>
                                </tr>
                              </table>
                            </td>
                          </tr>
                          <!-- Company & Customer Information -->
                          <tr class="information">
                            <td colspan="2">
                              <table>
                                <tr>
                                  <td>
                                    Company Name, Inc.<br>
                                    12345 Street Address<br>
                                    City, State, Zip
                                  </td>
                                  <td>
                                    Customer Name<br>
                                    Customer Company<br>
                                    67890 Customer Address
                                  </td>
                                </tr>
                              </table>
                            </td>
                          </tr>
                          <!-- Payment Method Details -->
                          <tr class="heading">
                            <td>Payment Method</td>
                            <td>Check #</td>
                          </tr>
                          <tr class="details">
                            <td>Check</td>
                            <td>1001</td>
                          </tr>
                          <!-- Itemized List of Services/Products -->
                          <tr class="heading">
                            <td>Item</td>
                            <td>Price</td>
                          </tr>
                          <tr class="item">
                            <td>Website Design</td>
                            <td>$300.00</td>
                          </tr>
                          <tr class="item">
                            <td>Hosting (3 months)</td>
                            <td>$75.00</td>
                          </tr>
                          <tr class="item last">
                            <td>Domain Registration (1 year)</td>
                            <td>$10.00</td>
                          </tr>
                          <!-- Total -->
                          <tr class="total">
                            <td></td>
                            <td>Total: $385.00</td>
                          </tr>
                        </table>
                      </div>
                    </body>
                    </html>
                # Give the pdf a name that is used when saved or shared.  
                fileName: invoice-1
            # Second action to save the file to the Dynamic database.   
            - type: action.execute-entity
              options: 
                provider: DATA_PROVIDER_DYNAMIC
                entity: default/documents
                method: create
                data:
                  # Enter the file name for database storage.
                  fileName: invoice
                  date: =$now()
                # Use the action instance output to reference the file
                # that is saved in dynamic data files.  
                file:
                  localPath: =@ctx.actions.generate-pdf-id.outputs.uri
            # Third action to share the file via the device's messaging app.        
            - type: action.share
              options:
                # Use the action instance output to reference the file.
                fileUri: =@ctx.actions.generate-pdf-id.outputs.uri
                # Provide a message and subject to accompany the share.
                message: Global Invoice 
                subject: Invoice for January

Generate pdf from JavaScript HTML function

This example demonstrates how to use a JavaScript function to generate an HTML invoice. The invoice is populated with customer details retrieved from a Dynamic Data datasource named invoices. The JavaScript function is referenced in an expression used by action.generate-pdf, after which the invoice is shared using the action.share via the device's apps.

Example: See the full code sample in GitHub.

title: Monthly invoicing
description: Provide your details
type: jig.default

header:
  type: component.jig-header
  options:
    height: small
    children: 
      type: component.image
      options:
        source:
          uri: https://images.unsplash.com/photo-1450101499163-c8848c66ca85?w=900&auto=format&fit=crop&q=60&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxzZWFyY2h8MTR8fGludm9pY2luZ3xlbnwwfHwwfHx8MA%3D%3D    
      
children:
  - type: component.section
    options:
      title: Details
      children: 
        - type: component.form
          instanceId: inputValues
          options:
            children:
              - type: component.text-field
                instanceId: customerCompany
                options:
                  initialValue: =@ctx.datasources.customer.customerCompany
                  label: First name
                  isRequired: false
              - type: component.text-field
                instanceId: firstName
                options:
                  initialValue: =@ctx.datasources.customer.firstName
                  label: First name
                  isRequired: false
              - type: component.email-field
                instanceId: email
                options:
                  initialValue: =@ctx.datasources.customer.email
                  label: Email address
              - type: component.number-field
                instanceId: phoneNumber
                options:
                  initialValue: =@ctx.datasources.customer.phoneNumber
                  label: Mobile number
# Create an action list that creates the PDF from the JavaScript HTML function,
# secondly share the pdf file via one of the devices apps.                      
actions:
  - children:
      - type: action.action-list
        options:
          title: Send Invoice
          isSequential: true
          actions:
            # First action to create the pdf.
            - type: action.generate-pdf
              instanceId: generate-pdf-id
              options:
                # Reference the JavaScript HTML function in an expression,
                # and provide the reference to the datasource for the inputs.
                html: 
                   =$html.generateHTML(@ctx.datasources.customer) 
                # Provide the name of the pdf.   
                fileName: invoice
            # Save the PDF to the database.    
            - type: action.execute-entity
              options: 
                provider: DATA_PROVIDER_DYNAMIC
                entity: default/documents
                method: create
                data:
                  fileName: invoice
                  date: =$now()
                file:
                  # Use the action instance output to reference the file
                  # that is stored in Dynamic data files.
                  localPath: =@ctx.actions.generate-pdf-id.outputs.uri
            # Add the second action to share out the pdf,
            # on one of the devices apps.       
            - type: action.share
              options:
                # Use the action instance output to reference the file.
                fileUri: =@ctx.actions.generate-pdf-id.outputs.uri
                message: Global Invoice 
                subject: Invoice for January

datasources:
  
  customer:
    type: datasource.sqlite
    options:
      provider: DATA_PROVIDER_DYNAMIC
      # Use isDocument true to record a single record.
      isDocument: true
      entities:
        - default/invoices
      query: |
        SELECT 
          id,
          '$.firstName',
          '$.email', 
          '$.phoneNumber',
          '$.customerCompany',
          '$.address'
        FROM [default/invoices] 
        WHERE firstName = 'John Smith'

// Create a JS function that generates HTML, reference the input fields from
// the datasource.
export function generateHTML(invoiceInfo) {
    const { firstName, customerCompany, address } = invoiceInfo;
// Specify what must be returned.
return `
    <!DOCTYPE html>
    <html lang="en">
    <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Invoice</title>
    <style>
            body {
            font-family: 'Arial', sans-serif;
            margin: 0;
            padding: 20px;
            background-color: #f6f6f6;
            }
            .invoice-box {
            max-width: 800px;
            margin: auto;
            padding: 30px;
            border: 1px solid #eee;
            box-shadow: 0 0 10px rgba(0, 0, 0, 0.15);
            background-color: #fff;
            color: #555;
            }
            .invoice-box table {
            width: 100%;
            line-height: 1.6;
            text-align: left;
            border-collapse: collapse;
            }
            .invoice-box table td {
            padding: 5px;
            vertical-align: top;
            }
            .invoice-box table tr td:nth-child(2) {
            text-align: right;
            }
            .invoice-box table tr.top table td {
            padding-bottom: 20px;
            }
            .invoice-box table tr.information table td {
            padding-bottom: 40px;
            }
            .invoice-box table tr.heading td {
            background: #eee;
            border-bottom: 1px solid #ddd;
            font-weight: bold;
            }
            .invoice-box table tr.details td {
            padding-bottom: 20px;
            }
            .invoice-box table tr.item td {
            border-bottom: 1px solid #eee;
            }
            .invoice-box table tr.item.last td {
            border-bottom: none;
            }
            .invoice-box table tr.total td:nth-child(2) {
            border-top: 2px solid #eee;
            font-weight: bold;
            }
            h2, h3 {
            margin: 0;
            }
        </style>
    </head>
    <body>
    <div class="invoice-box">
        <table cellpadding="0" cellspacing="0">
        <!-- Invoice Header -->
        <tr class="top">
            <td colspan="2">
            <table>
                <tr>
                <td class="title">
                    <h2>Global Inc</h2>
                </td>
                <td>
                    Invoice #: 12345<br>
                    Created: January 1, 2025<br>
                    Due: January 31, 2025
                </td>
                </tr>
            </table>
            </td>
        </tr>
        <!-- Company & Customer Information -->
        <tr class="information">
            <td colspan="2">
            <table>
                <tr>
                <!-- Specify the inputs from the datasource -->
                <td>
                    ${firstName || ''}<br>
                    ${customerCompany || ''}<br>
                    ${address || ''}<br>
                </td>
                <td>
                    Global Inc<br>
                    67890 First Avenue,<br>
                    New York,<br>
                    34567
                </td>
                </tr>
            </table>
            </td>
        </tr>
        <!-- Remaining HTML content -->
        <!-- Payment Method Details -->
            <tr class="heading">
                <td>Payment Method</td>
                <td>Check #</td>
            </tr>
            <tr class="details">
                <td>Check</td>
                <td>1001</td>
            </tr>
            <!-- Itemized List of Services/Products -->
            <tr class="heading">
                <td>Item</td>
                <td>Price</td>
            </tr>
            <tr class="item">
                <td>Website Design</td>
                <td>$300.00</td>
            </tr>
            <tr class="item">
                <td>Hosting (3 months)</td>
                <td>$75.00</td>
            </tr>
            <tr class="item last">
                <td>Domain Registration (1 year)</td>
                <td>$10.00</td>
            </tr>
            <!-- Total -->
            <tr class="total">
                <td></td>
                <td>Total: $385.00</td>
            </tr>
            </table>
        </table>
    </div>
    </body>
    </html>
`;

}

Previousgenerate-file

Nextgo-back

Last updated 3 months ago

Was this helpful?

Configuration options

Page options

Margin options

Page size and HTML layout

Multi-page rendering

Considerations

Examples and code snippets

Basic generate a PDF and share

Control page size, orientation, and margins

Multi-page HTML example

Generate a pdf, save and share

Generate pdf from JavaScript HTML function