Syntax for Advanced Template Fields

You can include the following field types for a record in an advanced template:

The template editor creates an XML document that uses syntax similar to HTML. Note that although this syntax can appear similar to SuiteScript, the template editor does not support the execution of SuiteScript APIs.

The fastest way to add a field to an advanced template is to select the field in the template editor’s Fields selector. (See Adding and Removing Fields in Advanced Templates.) If preferred, you can use FreeMarker syntax to add a field manually instead of using the Fields selector.

Subrecords are not supported in advanced templates, except for the list of inventory details values.

See the following:

Entering a Field Manually to an Advanced Template

Some fields can be added to advanced templates but are not available in the Fields selector, for example, ${record.entity.email} refers to the Customer record through the entity field so that all body fields in the customer record can be accessed.

The following procedure describes how to add fields to the template manually.

To manually add a field to an advanced template:

  1. Obtain the field ID for the field you want to add.

    • To make field IDs available, go to Home > Set Preferences and ensure that the Show Internal IDs box is checked on the General subtab, Defaults area.

    • Find the field in the NetSuite user interface and click the field label to display the field level help text.

      Advanced PDF/HTML Template Field Help example highlighting Field ID

      The field ID is displayed in the popup window.

    Note:

    Field ID information is also available in the SuiteBuilder Advanced Templates Reference.

  2. Go to Customization > Forms > Advanced PDF/HTML Templates and click Customize or Edit for the advanced template.

  3. Place the cursor in the location on the template where you want to add the field.

  4. Add a text field, and enter the appropriate syntax for the field that you want to add.

    The template editor supports a simplified syntax to get values for the fields to be printed. To see if a field is available in an advanced template, see SuiteBuilder Advanced Templates Reference.

    For information about entering the syntax, read Syntax for Body Fields, Syntax for Sublist Fields, and Syntax for Fields from Joined Records and Searches.

Syntax for Body Fields

For most template body fields, the syntax is ${object.fieldId}, for example, ${record.entity}.

  • The following objects are currently supported:

    • companyInformation - company information for the current NetSuite account

      For example, ${companyInformation.companyname} is the name associated with the NetSuite account.

      Enter ${subsidiary.mainaddress_text} to include the subsidiary address on a template.

    • record - current transaction record

      For example ${record.trandate} is the date of the transaction.

    • records - reference multiple data sources, which you typically need to do in label, check and statements templates, for example, ${statement.amountDue}.

    • customer - only available on Statement records, this includes customer-related information on the template. For example, you could include ${customer.subsidiary}, ${customer.subsidiary.legalname}, or ${customer.entityId}.

    • salesorder - available on packing slips

    • preferences - include settings entered on the Setup > Company > Printing & Fax page.

    • user - include settings entered on the user’s Set Preferences page. These fields are typically used for emails.

  • You can include fields that dynamically return a URL link to NetSuite pages, or to parts of a URL, such as the account ID:

    Note:

    In the following examples, replace the variable <accountID> with your account ID.

    • ${companyInformation.companyId} — Your NetSuite account ID.

    • ${companyInformation.appDomain} — Application domain, for example, <accountID>.app.netsuite.com.

    • ${companyInformation.customerCenterDomain} — Customer center domain, for example, <accountID>.app.netsuite.com.

    • ${companyInformation.customerLoginUrl} — Customer login URL, for example, https://<accountID>.app.netsuite.com/app/login/secure/privatelogin.nl?<accountID>

    • ${companyInformation.extformsDomain} — External forms domain, for example, <accountID>.extforms.netsuite.com.

    Note:

    To find your account ID, go to Setup > Company > Company Information. The Account ID field is at the bottom of the right column. To view the correct format for all your account-specific domains, click the Company URLs tab.

    To view Account ID and Company URLs, you must have the Administrator role or the Setup Company permission.

  • You can include fields from records related to the current transaction record if they are of type select (not sublists).

    • Syntax is ${record.related_record.fieldId}

      For example, to include customer field values from related item records in a sales order template, use the syntax: ${record.entity.email}. You can also refer to custom fields, for example, include a transaction column field on a purchase order template by entering ${record.expense.custcol_cc_oversize}.

  • The syntax for body fields can include an additional component, such as the following:

    • ${object.fieldId@label} - indicates the label of a field should be printed.

      For example, ${record.entity@label}: ${record.entity} indicates the label for the entity should be printed with the entity, that is, Customer: City Art Gallery. The label is the text that appears next to the field on the transaction form.

    • ${record@title} - indicates that the name of the transaction record type should be printed, for example, Sales Order for sales order.

      This can be used for record objects only. For other objects it will return a blank string.

  • Fields that include a link, such as images or URLs, are enclosed in an HTML element, for example, <img> or <a>. You have two options for link fields:

    • Use the field to include the HTML markup source. For example, ${record.hyperlink} returns the following:

      <a href src="http://www.netsuite.com">http://www.netsuite.com</a>

    • Add @url to the field to return the link without the HTML. For example, ${record.hyperlink@url} returns the following:

      http://www.netsuite.com

Syntax for Sublist Fields

Sublists are NetSuite components that are referenced as lists of objects. The most common example of a sublist is an item sublist on a transaction, which displays a list of lines. Sublists are not available in the Fields selector.

The most common way to access a sublist is by using the FreeMarker #list declaration. The following example shows an item sublist on the sales order.

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

          

This declaration prints out a block of HTML code to display the whole list.

            0 Name: Blue T-Shirt --- 10.00$
1 Name: Green T-Shirt --- 12.25$
2 Name: Yellow T-Shirt --- 11.00$ 

          

To reference one item in the list, you can use ${record.item[index].itemName} to obtain only that line in the sublist. Using the preceding example, ${record.item[1].itemName} returns the line 1 item Green T-Shirt.

The syntax for sublist (line item) fields is similar to body field syntax. Sublist fields are denoted with syntax like:

  • ${item.item@label}

  • ${item.id}

  • ${item.item}

  • ${item.quantity}

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> 

          

You can reference fields on a sublist at the first level only. Referencing sublists at the second level is not supported.

For example, only the following is supported.

            <#list record.item as item>
    ${item.field_first_level}
</#list> 

          

If you use item.inventorydetail, you will get a listing of all bin/serial numbers.

To sort line items in advanced templates, add the sort_by() function to the #list declaration, for example:

<#list record.item?sort_by("quantity") as item>

Syntax for Address Subrecords

For address subrecords, use the following syntax in the source code:

  • Record name

  • Address subrecord name

  • Address field name

For example:

  • ${subsidiary.mainaddress.addresee}

  • ${subsidiary.mainaddress.addr1}

  • ${subsidiary.mainaddress.addr2}

  • ${subsidiary.mainaddress.city}

  • ${subsidiary.mainaddress.dropdownstate}

  • ${subsidiary.mainaddress.zip}

  • ${subsidiary.mainaddress.country}

  • ${subsidiary.mainaddress.addrphone}

Syntax for Fields from Joined Records and Searches

You can modify advanced templates in the template editor to include fields from records directly joined to the current transaction.

  • Syntax is ${record.related_record.fieldId}

  • To include sales description field values from related item records in a sales order template, use the syntax: ${record.item.salesdescription}

You also can include search results fields from searches joined directly to the current transaction.

  • You can use the index number to indicate the search result row to be referenced to obtain a field value. For example, [0] would indicate that the field value from the first row returned in search results should be used.

  • Syntax is ${results[search_result_line].related_record.fieldId}.

    For example, to include the first customer phone number from a sales order search, type: ${results[0].customer.phone}

  • To include a list of search results, use a list directive as shown in the following example.

                    <#list results as salesOrder>
        <p>${salesOrder.customer.phone}</p>
    </#list> 
    
                  

FreeMarker Formatting Method

NetSuite formatting is lost when you customize NetSuite standard fields. If you print hard-coded values which came from a custom data source or were calculated from standard fields, the format will not be consistent with the format of standard record fields. When editing the template source code, the nsformat_*() formatting method makes it possible to format FreeMarker custom variables in the same way NetSuite formats standard fields. It also decreases the need for hardcoding. The nsformat_*() method formats the specific string, number, date, or amount results in the same format used on a standard NetSuite field. With this formatting method, it is possible to apply localization to custom variables, ensuring consistent output.

The following table shows some examples of standard fields in use:

Example

Output

${record.custbody_show_int}

1,234

${record.custbody_show_int+1}

1235

${nsformat_number(record.custbody_show_int+1)}

1,235

${record.custbody_show_date_time}

Dec 18, 2019 5:05:00 AM

The following table shows some examples of the ${nsformat_*() formatting method in use:

Method

Example

Output

${nsformat_date(date|string)}

${nsformat_date("2018-12-04T10:40:00.000")}

12/4/2018

${nsformat_datetime(date|string)}

${nsformat_datetime("2018-12-04T10:40:00.000Z")}

${nsformat_datetime("2018-12-04T10:40:00.000")}

${nsformat_datetime(itemDateTime)}

Dec 4, 2018 2:40:00 AM

Dec 4, 2018 10:40:00 AM

Dec 4, 2018 10:40:00 AM

${nsformat_time(date|string)}

${nsformat_time("2018-12-04T10:40:00.000")}

10:40:00 AM

${nsformat_currency(number|string)}  or with optional second string ${nsformat_currency(number|string, string)}

${nsformat_currency(10.20, "EUR")}

€10,20

${nsformat_rate(boolean|string|number)} or with optional second string ${nsformat_rate(number|string, string)}

${nsformat_rate(32, "USD")}

$32.00

${nsformat_number(number|string)} or with optional second string ${nsformat_number(record.field.”string”)}

${nsformat_number("999999999)}

${nsformat_999999999.99(item.quantity, “cs_CZ”)}

999 999 999

999 999 999.99

${nsformat_boolean(boolean|string|number)}

${nsformat_boolean("true")}

Yes

${nsformat_password(string)}

${nsformat_password("p4sw0rd")}

*****

${nsformat_percent(number|string)}

${nsformat_percent("100")}

100%

${nsformat_email(string)}

${nsformat_email(“email@example.com”)}

clickable email address

${nsformat_url(string)}

${nsformat_url(“http://example.com”)}

clickable link

Formatters accept numbers in double precision floating point representation.

If the input is an empty string or null value, then the output is also represented as an empty string.

Updating a Statement Template to Support Multiple Currencies

If you have an advanced statement template that must be updated to support multiple currencies, edit your template as follows.

Wrap the existing template in the following tags:

            <pdfset>
<#list statements as record>
    ...original template...
</#list>
</pdfset> 

          

Change any record.items references to record.lines.

File Cabinet FreeMarker Directive

If you edit templates in the source code, you can use the filecabinet FreeMarker directive to reference files directly from the File Cabinet. By using this directive, you can embed text, images, and fonts that are stored in the File Cabinet into the template.

For example:

            <@filecabinet nstype="image" src="https://<accountID>.app.netsuite.com/core/media/media.nl?id=21&c=4130331&h=fb3b8b4ac4f67b2c369b"/> 

          

When you add an image to a template and check the File Cabinet Item box, the <@filecabinet/> directive is used in the source code.

For more information about the File Cabinet, see File Cabinet Overview.

For more information about including images in advanced templates, see Including Images in Advanced Templates.

Related Topics

Source Code Editing in the Template Editor
Source Code Editing to Customize Advanced Templates
Setting a Template to Use a Font Unavailable in NetSuite
Languages for Printed Forms that Use Advanced Templates
Adding Translated Content in Advanced Printouts
Adding Striping to Line Items in Advanced Templates
Adding Page Breaks to Tables
Printing Subsidiary Logo on Advanced Templates
Adding Apply Sublist to Check Templates
Using FreeMarker to Work with Hidden Fields Used in Advanced Templates
Adding Bar Codes in Advanced Templates

General Notices