DRAFT How to use JavaScript in HTML invoice templates

Configuring barcodes

In HTML invoice templates, you can configure barcodes by using the Wp_Barcode merge field. However, currently, this merge field only supports popular barcode types. For more information, see Configure barcodes in HTML invoice templates.

If your business requires a barcode that is not included in the list of supported barcode types, you can either leverage the JavaScript library approach or submit your request in Zuora Community. You can also use JavaScript in HTML invoice templates to generate barcodes including Swiss QR codes, use your own fonts for barcode text, configure S, and configure QR code styling. For more use cases, see Use JavaScript in your template.

To use JavaScript in HTML invoice templates to generate barcodes, perform the steps documented in Add JavaScript codes to HTML invoice templates. In this use case, you can type the following JavaScript codes in the HTML code editor:

<!-- ① -->
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/bwip-js/3.0.4/bwip-js.min.js"></script>
<!-- ② -->
<canvas id="qrcodeCanvas"></canvas>
<script>
  try {
    // The return value is the canvas element
    let canvas = bwipjs.toCanvas('qrcodeCanvas', {
        bcid:        'qrcode',       // Barcode type
        text:        '{{Invoice.InvoiceNumber}}',    // ③
    });
  } catch (e) {
      // `e` may be a string or Error object
  }
</script> 

When previewing the template, you can see the following QR code displayed on the generated invoice PDF file:

In the preceding JavaScript code snippet, bwip-js is a JavaScript library to generate various barcode images, and it is just used for demonstration purposes in this article. You can use your own JavaScript library to generate barcodes.

Read the following information to understand how data transformation works in the preceding output:

• ①: Loads the bwip-js library when rendering the HTML.
• ②: Creates a canvas element to draw the barcode image.
• ③: Replaces the merge field with a real invoice number.
  Keep in mind that the merge field substitution occurs before the HTML rendering, so the qrcode content is replaced with something like INV00000028.

The bwip-js library supports various barcode types. For more information, see the full list of supported BWIPP barcode types and Symbologies Reference.

<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/bwip-js/3.0.4/bwip-js.min.js"></script>
<canvas id="barcodeCanvas" style="width:46mm;height:46mm;"></canvas>       
<script>    
  try {
    // The returned value is the canvas element
    let canvas = bwipjs.toCanvas('barcodeCanvas', {
        bcid:        'swissqrcode',
        text:        `SPC
0200
1
CH5800791123000889012
S
Robert Schneider AG
Rue du Lac
1268
2501
Biel
CH







199.95
CHF
K
Pia-Maria Rutschmann-Schnyder
Grosse Marktgasse 28
9400 Rorschach


CH
SCOR
RF18539007547034

EPD`,
      scale: 2
    });
  } catch (e) {
      // `e` might be a string or Error object
  }
</script>

<canvasid="barcodeCanvas"style="width:46mm;height:46mm;"></canvas>

Configuring charts

When configuring an HTML invoice template, you can also use JavaScript to add charts like a bar chart or pie chart to the template.

For example, if you want to create a bar chart by using the Chart.js library, type the following JavaScript codes in the HTML code editor:

<script src="https://cdn.jsdelivr.net/npm/chart.js@3.7.0/dist/chart.min.js"></script>
<!-- container needs to use relative position -->
<div style="width: 100%;display: flex; justify-content: center;">
    <div class="chart-container" style="position: relative; height:200px; width:400px;">
        <div>
            <canvas id="myChart" style="margin: 0 auto;"></canvas>
        </div>
        <script>
            const ctx = document.getElementById('myChart').getContext('2d');
            const myChart = new Chart(ctx, {
                type: 'bar',
                data: {
                    labels: [{{#Invoice.Account.Invoices|SortBy(InvoiceDate,ASC)}}"{{InvoiceDate}}",{{/Invoice.Account.Invoices|SortBy(InvoiceDate,ASC)}}],
                    datasets: [{
                        label: 'Invoice Trend',
                        data: [{{#Invoice.Account.Invoices|SortBy(InvoiceDate,ASC)}}{{Amount}},{{/Invoice.Account.Invoices|SortBy(InvoiceDate,ASC)}}],
                        backgroundColor: [
                            'rgba(255, 99, 132, 0.2)',
                            'rgba(54, 162, 235, 0.2)',
                            'rgba(255, 206, 86, 0.2)',
                            'rgba(75, 192, 192, 0.2)',
                            'rgba(153, 102, 255, 0.2)',
                            'rgba(255, 159, 64, 0.2)'
                        ],
                        borderColor: [
                            'rgba(255, 99, 132, 1)',
                            'rgba(54, 162, 235, 1)',
                            'rgba(255, 206, 86, 1)',
                            'rgba(75, 192, 192, 1)',
                            'rgba(153, 102, 255, 1)',
                            'rgba(255, 159, 64, 1)'
                        ],
                        borderWidth: 1
                    }]
                },
                options: {
                    responsive: true,
                    maintainAspectRatio: false,
                    scales: {
                        y: {
                            beginAtZero: true
                        }
                    }
                }
            });
            // resize the canvas size
            myChart.canvas.parentNode.style.width = "400px";
            myChart.canvas.parentNode.style.height = "200px";
            </script>
    </div>
</div>

When previewing the template, you can see the following bar chart displayed on the generated PDF file:

In the preceding code example, the important lines are as follows:

data: {
  labels: [{{#Invoice.Account.Invoices|SortBy(InvoiceDate,ASC)}}"{{InvoiceDate}}",{{/Invoice.Account.Invoices|SortBy(InvoiceDate,ASC)}}],
...
  datasets:[{
    data: [{{#Invoice.Account.Invoices|SortBy(InvoiceDate,ASC)}}{{Amount}},{{/Invoice.Account.Invoices|SortBy(InvoiceDate,ASC)}}],
...
}],
...
}

The labels property iterates a list section Invoice.Account.Invoices|SortBy(InvoiceDate,ASC), and constructs an array of InvoiceDate, which is used to anchor the bar on the X-axis. And similarly, the data property constructs the dataset for the Y-axis.

Sending outgoing requests

With JavaScript, you can also send outgoing requests to fetch external data and use it in your HTML invoice templates.

For example, if you do not want to use either the Wp_Barcode merge field or JavaScript libraries to generate barcodes, instead, you have an API endpoint returning a barcode image. With JavaScript, you can fetch that image and add it to an HTML invoice template.

The following information is a JavaScript code sample that you can use to issue an outgoing request to fetch JSON data from GitHub:

<div id="main"></div>
<script>
fetch('https://api.github.com/orgs/zuora')
  .then(response => response.json())
  .then(data => {
    document.getElementById('main').innerHTML = JSON.stringify(data);
  })
  .catch(error => document.getElementById('main').innerHTML = error)
</script>

The following data is the example JSON data that you use the preceding JavaScript code sample to fetch from GitHub:

{
    "avatar_url": "https://avatars.githubusercontent.com/u/241160?v=4",
    "blog": "https://www.zuora.com",
    "company": null,
    "created_at": "2010-04-10T18:45:26Z",
    "description": "",
    "email": null,
    "events_url": "https://api.github.com/orgs/zuora/events",
    "followers": 0,
    "following": 0,
    "has_organization_projects": true,
    "has_repository_projects": true,
    "hooks_url": "https://api.github.com/orgs/zuora/hooks",
    "html_url": "https://github.com/zuora",
    "id": 241160,
    "is_verified": false,
    "issues_url": "https://api.github.com/orgs/zuora/issues",
    "location": "San Mateo, CA",
    "login": "zuora",
    "members_url": "https://api.github.com/orgs/zuora/members{/member}",
    "name": "Zuora",
    "node_id": "MDEyOk9yZ2FuaXphdGlvbjI0MTE2MA==",
    "public_gists": 0,
    "public_members_url": "https://api.github.com/orgs/zuora/public_members{/member}",
    "public_repos": 1,
    "repos_url": "https://api.github.com/orgs/zuora/repos",
    "twitter_username": null,
    "type": "Organization",
    "updated_at": "2021-08-18T01:58:43Z",
    "url": "https://api.github.com/orgs/zuora"
}

When previewing the template, you can see the following JSON data displayed on the generated invoice PDF file: