NetSuite PDF template source mode gives administrators direct access to the markup behind an Advanced PDF/HTML Template. Instead of changing only visible elements in the visual editor, we can inspect and edit the XML-compatible HTML, FreeMarker expressions, CSS, record fields, and document structure that NetSuite uses to generate a PDF.
That access is powerful, but it also changes how we need to think about template customization. A PDF template is not simply a graphic layout. It is a data-driven document that combines a fixed page design with dynamic NetSuite values and conditional logic. A small syntax error can prevent the document from rendering, while an incorrect field reference can produce an empty or misleading result.
NetSuite PDF template source mode is the best place to make precise structural, data-binding, and formatting changes that are difficult or impossible to complete in the visual editor. We use it to inspect the template’s underlying markup, connect fields such as `${record.tranid}` to the output, add FreeMarker conditions and loops, control tables and page breaks, and adjust styles with greater precision. The safest method is to duplicate the template first, change one area at a time, save a controlled version, and test it against multiple record conditions before making it active.
What is NetSuite PDF template source mode?
NetSuite PDF template source mode is the code view for an Advanced PDF/HTML Template. It exposes the document structure that NetSuite processes when it creates a transaction PDF, including the `` document definition, page settings, styles, tables, FreeMarker expressions, and references to NetSuite record data.
The template generally combines three layers:
XML-compatible HTML, which defines the document structure.
FreeMarker, which supplies values, conditions, loops, and reusable logic.
CSS and PDF instructions, which control typography, spacing, tables, page behavior, and other visual details.
For example, this expression prints the transaction number when the `record` object exposes that field:
${record.tranid}The expression does not create a new NetSuite field. It reads a value from the record data available to the template at rendering time. That distinction matters because a correct-looking expression can still produce no output if the field is unavailable in that template context, is empty on the current record, or uses the wrong object path.
Source mode therefore acts as both a layout editor and a lightweight programming environment. We need to understand document structure, data availability, conditional logic, and rendering behavior together.
For the general debugging process, see our guide on using NetSuite Advanced PDF source code for faster template debugging. This introduction focuses on understanding source mode before troubleshooting a specific broken output.
How do you open source code mode in NetSuite?
You open source mode by editing an Advanced PDF/HTML Template from NetSuite’s customization area. The precise labels can vary slightly with account configuration and permissions, but the standard path is:
Customization > Forms > Advanced PDF/HTML Templates
From the template list, open an existing template or create a new one. NetSuite’s template editor provides a visual design experience and a source-oriented view. The source view exposes the markup that the visual editor abstracts away.
Before editing, confirm that your role has permission to access and modify Advanced PDF/HTML Templates. Also verify that you are working with the correct transaction form or template. A common source of confusion is editing a valid template that is not the one assigned to the transaction form being tested.
The template assignment determines what users actually see. If a source change appears to have no effect, the first question should be whether the transaction is using that template. Check the transaction form, subsidiary configuration, custom form behavior, and any advanced PDF preference that affects the output.
Source mode is also sensitive to how changes are saved. We recommend the following sequence:
Duplicate the original template and give the copy a clear internal name.
Record which transaction form and document type use the template.
Make one focused change rather than combining layout, field, and conditional logic changes.
Save and preview the copied template.
Test the output using records with different field values and line counts.
Promote the revised template only after the output is readable and accurate.
The duplication step is more than a general precaution. It creates a rollback point and helps separate a source-code problem from a template-assignment problem.
What does the source code contain?
The source code contains the instructions that determine how NetSuite turns record data into a PDF. The exact contents differ by template, but most Advanced PDF/HTML Templates include a document declaration, page configuration, styles, a body, and dynamic data expressions.
A simplified structure might look like this:
<?xml version="1.0"?>
<!DOCTYPE pdf PUBLIC "-//big.faceless.org//report"
"report-1.1.dtd">
<pdf>
<head>
<style type="text/css">
body {
font-family: sans-serif;
font-size: 9pt;
}
</style>
</head>
<body>
<h1>${record.tranid}</h1>
</body>
</pdf>The declaration and doctype are significant. NetSuite’s PDF generation process relies on a PDF rendering engine with its own supported markup and layout behavior. Browser HTML support is not a reliable indicator of PDF support. A design that looks acceptable in a browser can render differently, fail to render, or ignore unsupported CSS when processed as a PDF.
The source commonly includes:
Document and page configuration. The `` root element, page size, margins, headers, footers, and page numbering establish the document framework.
Record data. Expressions such as `${record.tranid}`, `${record.entity}`, or `${record.total}` connect the document to transaction values. The valid fields depend on the record and data context.
Line-item loops. A transaction table often iterates over an item collection with FreeMarker directives such as `<#list ... as item>`. This is how one source template prints a variable number of lines.
Conditional sections. FreeMarker conditions can display tax information, shipping details, discounts, subsidiary content, or other sections only when relevant.
Styles and tables. Most stable PDF layouts rely heavily on tables, explicit widths, controlled font sizes, and predictable spacing. PDF output is fixed-layout output, so flexible web-page techniques do not always translate well.
Escaping and formatting. Values containing special characters need appropriate handling. A raw ampersand or angle bracket inside XML-compatible markup can cause parsing problems if the value is not escaped correctly.
Understanding these layers helps us identify the type of change before editing. A missing value is usually a data-binding or conditional issue. A misplaced section is usually a structure or table issue. A rendering failure is frequently an XML, directive, or unsupported-markup issue.
What can you change in NetSuite PDF template source mode?
Source mode supports changes that go beyond visual positioning. It is especially useful when the required result depends on data, repetition, or conditions.
Field references and data binding
You can place NetSuite record fields in headings, addresses, transaction summaries, line tables, and footer content. The critical point is to use the correct object and field path for the template context.
A field reference should be tested against real records. A field that is populated on one transaction might be empty on another. Custom fields also require the correct internal ID and access to the expected data object. Do not assume that a label shown on the NetSuite form is the same as the field identifier used by the template.
Conditional output
FreeMarker conditions allow a template to display content only when a value or condition is present. A conceptual example looks like this:
<#if record.memo?has_content>
<p>${record.memo}</p>
</#if>This prevents an empty label or unnecessary blank area when the memo field has no content. Similar logic can control subsidiary-specific branding, tax sections, shipping addresses, or payment instructions.
Conditions need deliberate fallback behavior. If a section is hidden when a value is absent, confirm that the remaining layout still closes cleanly and does not leave an unwanted gap or broken table row.
Repeating transaction lines
Line-item tables are one of the main reasons administrators use source mode. A loop can print a row for each item, service, expense, or other transaction line.
The loop itself is only part of the design. The table also needs sensible column widths, header behavior, numeric alignment, wrapping rules, and handling for long descriptions. A fixed PDF page does not automatically adapt gracefully when a description expands to several lines.
Page headers, footers, and page numbers
Source mode provides more direct control over repeated document elements. Headers and footers need to be tested with one-page and multi-page transactions because a layout that appears correct in a short preview may overlap the body or create unexpected spacing once content flows onto another page.
Page numbers also require testing with the actual PDF output. Preview behavior is useful, but it does not always expose every pagination issue.
Fonts, logos, and branding
You can define fonts, colors, logos, and other branding elements in the source. Custom fonts require particular care because the rendering environment must be able to use the font correctly. If a font is unavailable or unsupported, the PDF may fall back to another font and change line wrapping across the document.
Images need appropriate dimensions and stable references. An oversized logo can force a header to expand, which then shifts the entire body downward. A source-level change should therefore be evaluated for its effect on page flow, not only its appearance in isolation.
How should beginners read the source code?
Beginners should read source code from the outside inward. Start with the document root and page settings, then identify the header, body, main transaction table, totals, and footer. This is more reliable than searching immediately for the visual text that needs changing.
Look for repeated patterns. An opening tag, a FreeMarker directive, or a table row should have a corresponding closing element. For example, `<#if>` needs ``, `<#list>` needs ``, and every XML or HTML element must be nested correctly.
Indentation is not what makes the template valid, but consistent indentation makes errors easier to see. We recommend aligning nested tables and directives so that the relationship between structure and logic is visible. Comments are useful when they explain a deliberate workaround, a business rule, or a non-obvious field relationship.
Source mode also rewards small, identifiable edits. If a change involves a field reference, do not simultaneously redesign the table and change the font system. When the output changes unexpectedly, a narrow edit gives you a realistic path to finding the cause.
A useful mental model is:
Markup answers: Where does this content appear?
FreeMarker answers: When does it appear and what data does it use?
CSS answers: How does it look?
PDF behavior answers: How does it flow across fixed pages?
When these responsibilities are mixed together, troubleshooting becomes slower. When they are separated, source mode becomes much easier to navigate.
Why does source mode sometimes produce blank or broken PDFs?
A blank or broken PDF typically results from invalid markup, an unclosed FreeMarker directive, an unavailable field, unsupported styling, or a template assignment problem. The most effective response is to isolate the last change rather than redesign the entire document.
XML-compatible syntax is a frequent issue. An unescaped character, mismatched tag, or incorrectly nested table can prevent the renderer from interpreting the document. FreeMarker errors create a separate class of problem. A directive may be valid in principle but fail because the referenced object does not exist in the current context.
A field can also be syntactically correct and still produce no visible value. For example, an expression may point to a field that is empty on the selected transaction. Test both a populated record and an intentionally empty record to distinguish a missing value from a broken expression.
CSS creates another source of confusion. Browser-oriented CSS, modern layout systems, and unsupported properties should not be assumed to work in NetSuite’s PDF renderer. Tables, explicit widths, standard font declarations, and conservative styling produce more predictable results than relying on responsive web behavior.
Preview should be treated as one test, not the final test. Download the generated PDF and inspect it separately. Test long addresses, multiple transaction lines, empty optional fields, discounts, taxes, and enough content to create more than one page. These conditions expose issues that a short sample cannot reveal.
Is source mode better than the visual editor?
Source mode is better for logic, precise structure, repeated content, and advanced formatting. The visual editor is better for simple adjustments where the desired change is limited to basic placement, text, or styling.
The two modes are not competing replacements. They address different levels of control. A visual editor can help a user understand the broad layout, but it may conceal the field expression, table nesting, or conditional directive responsible for the final output. Source mode reveals those mechanisms directly.
Use the visual editor when the change is straightforward and does not depend on data logic. Use source mode when you need to add a field, repeat line items, hide a section conditionally, control a page break, modify a complex table, or diagnose why the output differs from the expected record.
Frequent switching between modes deserves caution. A visual editor may reformat or rewrite parts of the underlying markup. Preserve a source copy before making substantial changes, and compare the source after saving if the template has complex logic.
How much does NetSuite PDF source mode customization cost?
NetSuite PDF source mode customization does not have one standard price. The effort depends on whether the work involves a single field, a table redesign, conditional business rules, custom data supplied through SuiteScript, font or image handling, or a broader document family.
A simple label or field change is materially different from building a multi-page transaction template with several record conditions. The number of templates, testing requirements, approval process, and need for SuiteScript data preparation also affect the work involved.
The right starting point is to define the output requirement and identify the source of the data. If the needed value already exists in the template context, a source edit may be sufficient. If the value requires a saved search, joined data, or custom calculation, the solution may include SuiteScript or another NetSuite customization.
We recommend documenting the affected template, transaction type, required fields, sample conditions, and acceptance criteria before estimating the work. If you want help assessing the scope, contact Versich about your NetSuite template requirements.
Conclusion
NetSuite PDF template source mode provides direct control over the structure and behavior of Advanced PDF/HTML Templates. It lets administrators work with record fields, FreeMarker logic, XML-compatible markup, CSS, tables, page settings, and document conditions that the visual editor does not fully expose.
The safest approach is disciplined rather than complicated. Duplicate the template, confirm the assignment, understand the source structure, make one focused change, and test both populated and empty data conditions. Then inspect the downloaded PDF across short and multi-page records before publishing the revision.
When source mode is treated as a data-driven document system rather than a simple design canvas, it becomes a practical way to create accurate, maintainable NetSuite PDF output.
