Source Code Editing to Customize Advanced Templates

Important:

When using advanced templates, follow the syntax and usage guidelines in the BFO and FreeMarker documentation. 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's 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. You can't use HTML5 declarations. 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, 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. The following sections describe some commonly-used BFO elements.

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, you can't use them as values in FreeMarker declarations.

Headers, Footers and Background Macros

You can use BFO functionality to define macros to repeat pieces of HTML code on every page. You can define each macro in the head part of the template inside the <macrolist> tag. To apply the macro, you reference it in the <body> tag definition. You can't create multiple headers for a template. Also, you must declare a height for header and footer macros or they won't 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're having issues with your advanced template, don't contact BFO directly. Always contact NetSuite Customer Support.

Bar Codes

When using advanced printing templates, 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 that generates 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 with its value in the output. 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. To reference a field, use ${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, use ${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

Some components in NetSuite can be referenced as lists 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.

More commonly, you can access 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 has three lines, the output looks 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 on that page shows how to include field IDs and sublists from NetSuite transaction records in advanced templates.

Additional Information to Include on Templates

You can access additional models 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

BFO and FreeMarker work differently from the HTML 4 specification, which can affect how your advanced templates are formatted. 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're used with BFO. For example, the non-breaking space ( ) character isn't rendered when using advanced templates. Use a line break element (<br />) instead of the   character.

If you're 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.