Source Code Editing to Customize Advanced Templates

Important:

When using advanced templates, you must follow the syntax and usage guidelines included in the documentation for BFO and FreeMarker. For version details, see Third-Party Products Used in Advanced Printing. For more information, see the BFO website, and FreeMarker website.

An advanced template that is used to print a PDF file is an XML document that uses syntax similar to HTML with FreeMarker and BFO (Big Faceless Organization) report generator elements included. For example:

           <?xml version="1.0"?>
 <!DOCTYPE pdf PUBLIC "-//big.faceless.org//report" "report-1.1.dtd">
 <pdf>
     <head>
     </head>
     <body>
          Hello, World!
     </body>
 </pdf>

Line 1 of the template must declare the XML version, and Line 2 must specify the DOCTYPE. Line 3 includes the BFO <pdf> wrapping tag, not the <html> declaration you would see at the top of an HTML document.

Inside the <pdf> tag, the head and body elements contain standard HTML, and you can embed CSS2 elements. HTML5 declarations are not allowed. The example displays the text "Hello, World!". For more information about the Big Faceless Report Generator, see BFO User Guide.

In XML, elements must always be closed. As shown in Line 8, <pdf> must always be matched by </pdf>, <b> by </b> and so on. For elements that have no content, like <br>, the closing tag is included in the element: <br />. Any attributes must have quotes around them, for example, <table width=”100%”>.

If a PDF template is used to print in HTML, the <pdf> tags are automatically converted to <html> when the document is printed.

Important:

For issues with NetSuite advanced templates, ensure that you contact NetSuite Support.

BFO Elements

BFO (Big Faceless Organization) is a Java application that converts documents written in XML to PDF. BFO is used in NetSuite. For version details, see Third-Party Products Used in Advanced Printing. Some commonly-used BFO elements are described in the following sections.

Page Numbers

The most-commonly used BFO elements in PDF templates are page number and total pages. The <pagenumber /> and <totalpages /> tags insert the current page number and total number of pages. Because these values are known at the last part of rendering the page, they cannot be used in FreeMarker declarations as values.

Headers, Footers and Background Macros

You can use BFO functionality to define macros to repeat pieces of HTML code on every page. Each macro is defined in the head part of the template inside the <macrolist> tag. To apply the macro, you reference it in the <body> tag definition. It is not possible to create multiple headers for a template. Also, header and footer macros must have a height declared or they will not be applied. See the following example.

              <?xml version="1.0"?>
<!DOCTYPE pdf PUBLIC "-//big.faceless.org//report" "report-1.1.dtd">
<pdf>
    <head>
        ...
        <macrolist> <!-- Definition of macros -->
            <macro id="nlHeader"> <!-- Regular macros -->
                ... Header Content ...
            </macro>
            <macro id="nlFooter">
                ... Footer Content ...
            </macro>
            <macro id="nlWatermark">
                ... Footer Content ...
            </macro>
            <macro id="nlAltHeader"> <!-- Alternative macros -->
                ... Header Content ...
            </macro>
            <macro id="nlAltFooter">
                ... Footer Content ...
            </macro>
            <macro id="nlAltWatermark">
                ... Footer Content ...
            </macro>
        </macrolist>
        ...
    </head>
    <body header="nlHeader" header-height="2.5in" footer="nlFooter" footer-height="0.5in" background-macro="nlWatermark">
        ... Body Content each page with regular header, footer and watermark ...
        <pbr header="nlAltHeader" header-height="2.2in" footer="nlAltFooter" footer-height="0.3in" background-macro="nlAltWatermark" />
        ... New page with alternative header, footer and watermark ...
        ... After that each page with regular header, footer and watermark ...
    </body>
</pdf>

Note:

If you are having issues with your advanced template, do not contact BFO directly. Always contact NetSuite Customer Support.

Bar Codes

When using an advanced printing template, you can add any type of bar code or QR code listed in the Barcodes section of the BFO User Guide. In the template, create a field with a value that can be passed in as the value of that bar code type.

The bar code syntax is shown in the following example.

              <barcode codetype="qrcode" showtext="false" height="150" width="150" value="http://www.example.com/" />

Using FreeMarker to Include NetSuite Data

FreeMarker is a Java library used to generate text outputs based on templates and dynamic data. FreeMarker is used in NetSuite. For version details, see Third-Party Products Used in Advanced Printing. You use FreeMarker interpolations to include NetSuite data in your template. An interpolation is an expression, such as ${‌record.entity} that FreeMarker replaces in the output with the value of the expression. A few common uses for FreeMarker declarations are provided in the following sections. For complete information about FreeMarker, see the FreeMarker documentation.

Referencing Fields

FreeMarker is commonly used to reference fields on transaction records. The syntax to reference a field is ${‌record.fieldId}. In the output, this interpolation is replaced with a text representation of the field’s value.

If you want to print the field’s label, the syntax is ${record.fieldId@label}. For example, ${record.entity@label}: ${‌record.entity} can produce something on the Sales Order record that looks like Customer: Fabre Art Gallery.

Sublists and Other Lists

There are some components in NetSuite that can be referenced as a list of objects. The most common example is an item sublist on a transaction, which is represented as a list of lines. You can access values of these lists directly using the index number ${record.list[index]}. For example, adding ${record.item[1].itemName} to a sales order returns Green T-Shirt.

The more common way of accessing a list is by using the FreeMarker #list declaration, similar to the following.

              <#list record.item as item>
    ${item_index} ${item.itemName@label} ${‌item.itemName} --- ${‌item.amount}
</#list>

If the item sublist on the sales order had three lines, the output would look like the following.

0 Name: Blue T-Shirt --- 10.00$

1 Name: Green T-Shirt --- 12.25$

2 Name: Yellow T-Shirt --- 11.00$

When the sublist ID is the same as the field ID, @list is added to the sublist ID. The correct syntax appears in the Fields selector automatically. The following example shows the syntax to access a sublist:

              <#list customer.currency@list as customerCurrency>
 ${‌customerCurrency.currency} <br/>
 ${‌customerCurrency.balance}
</#list>

To view the sublists that are supported for a record, see the Advanced Templates Reference.

For more information about using FreeMarker expressions in advanced PDF/HTML templates, see Using FreeMarker to Include NetSuite Data. The training video that is available from the page describes how to include field IDs and sublists from NetSuite transaction records in advanced templates.

Additional Information to Include on Templates

There are additional models that can be accessed on each template. These include companyInformation (Company configuration information), preferences (user preference settings usually stored as Boolean values) and user (user information).

Some templates can have additional models attached, enabling you to access additional data. For example, you can access the customer record on each statement, such as the customer email, ${‌customer.email}.

You can also use ${record@title} to print out the record title.

Differences from HTML 4 Specification

The implementations of BFO and FreeMarker include some important differences from the HTML 4 specification. These differences can affect the formatting of your advanced templates. For more information, see the Element and Attribute Reference for BFO at http://bfo.com/products/reports/docs/tags/.

Certain characters behave differently when they are used with BFO. For example, the non-breaking space ( ) character is not rendered when using advanced templates. In general, use a line break element (<br />) instead of the   character.

If you are using the   character to create spacing in HTML table layouts, use the width and height attributes of the <td> tag instead to specify how BFO formats the <table> tag. For example:

            <table table-layout="fixed" width="200"> <tr><td width="60%">Cell 1</td><td width="40%">Cell 2</td></tr> <tr><td>Cell 3</td><td>Cell 4</td></tr>
</table>

For more information about tables in BFO, see the BFO TABLE element documentation at http://bfo.com/products/report/docs/tags/tags/table.html.