XML Elements
Introduction
XML elements define the layout of PDF reports.
You use XML elements when creating XML templates to build PDF reports.
This article explains how to use XML elements.
Remember the following conversions when building PDF reports:
|
Core Elements
<template>
Base element for an XML template.
Guidelines |
Example 1. Use the following code to add a
<template> element with standard settings.
|
Guidelines
-
You only need to add one
<template>
element per XML template. -
Once you add a
<template>
element, you can add other elements inside of it to build the structure of report pages.Figure 2. A report page with header, footer, and body sections that repeat on every page. -
Spaces are not allowed in the
name
attribute of any element.To aid readability, use camelCase.
For example,
name="Company Logo"
is invalid.
Usename="companyLogo"
orname="company-logo"
instead. -
Use the
pageMargins
attribute to define the margins for report pages.-
When you set the top margin for a page, you must make it big enough to contain the
<header>
element. -
When you set the bottom margin for a page, you must make it big enough to contain the
<footer>
element. -
When you set left and right margins for a page, they don’t apply to
<header>
and<footer>
elements.
-
Set the
|
<template>
element with standard settings.<template pageSize="LETTER" pageOrientation="portrait" pageMargins="36 36 36 36">
<header>header text</header>
<body>body text</body>
<footer>footer text</footer>
</template>
<info>
-
PDF Templates can specify the resulting PDF’s Title and other metadata
-
Use the
<info>
tag to add metadata about the PDF file -
Use Handlebars expressions in the
<info>
helper to dynamically update metadata
Guidelines
-
The
<info />
tag must be a child of the<template>
tag.<template> <info title="Job Safety" /> </template>
Attributes
<info />
must have at least one attribute.
The <info>
tag supports the following metadata attributes:
-
title
This attribute is used as both as the PDF’s Title metadata and also the resulting PDF’s file name
-
author
-
subject
-
keywords
Each attribute expects a text string that can contain a Handlebars expression.
Examples
Add the following line inside the PDF template’s <template>
tag:
<template>
<info title="Job Safety Report" />
</template>
Add the following Handlebars expression to the title
attribute of the info
report helper inside the <template>
tag:
<template>
<info title="{{FX5__Customer_Account__r.Name}}-{{formatDate (formula "NOW()") format="MM/DD/YYYY HH:mm:ss"}}"/>
</template>
Generating reports for such a report results in the following:
Reports Tab in FieldFX Mobile
Note List in FieldFX Back Office
File Properties Details Tab
On Windows, right clicking the PDF file and selecting the Properties option, then the Details tab, shows:
<header>
Inserts a repeating header at the top of every report page.
Guidelines
-
You can only add one
<header>
element per XML template. -
To prevent content from being cutoff, make sure that the height of a
<header>
element is sufficient to show its contents.
Placeholders
Use the following placeholders to insert page data into a <header>
element:
Placeholder | Description |
---|---|
|
Inserts the current page number |
|
Inserts the page count for the report |
<header>
<text>Page $currentPage of $pageCount</text>
</header>
-
This example uses the
$currentPage
placeholder to insert the current page number. -
The
$pageCount
placeholder inserts the page count for the report. -
A result of this would be the text
Page 2 of 4
in the Header on the second page of a four-page report.
<footer>
Inserts a repeating footer at the bottom of every report page.
Guidelines
-
You can only add one
<footer>
element per XML template. -
To prevent content from being cutoff, make sure that the height of a
<footer>
element is sufficient to show all contents.
Placeholders
Use the following placeholders to insert data into a <footer>
element:
Placeholder | Description |
---|---|
|
Inserts the current page number |
|
Inserts the page count for the report |
<footer>
<text>Page $currentPage of $pageCount</text>
</footer>
-
This example uses the
$currentPage
placeholder to insert the current page number. -
The
$pageCount
placeholder inserts the page count for the report.
<background>
-
Inserts a repeating background image into the
<template>
element.Figure 5. A background sits behind the content of the report and can be used for adding watermarks -
The
<background>
element is behind the main section of a report. -
Use the
<background>
element to create a watermark in the report.
Guidelines
You can only add one <background> element per <template> element.
|
<background>
element into a <template>
element<template xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" pageSize="LETTER" pageOrientation="portrait" pageMargins="36 225 36 36" xsi:noNamespaceSchemaLocation="fx-report-schema.xsd">
<background>
<image name="pagewm" marginTop="144" width="450"/>
</background>
<body>
<text>Hello {{FX5__Tracking_Number__c}}</text>
</body>
<images>
<image name="pagewm" src="data:image/png;base64,BASE64STRING"/>
</images>
</template>
Replace BASE64STRING with the base64 string for your image.
|
<body>
-
Inserts a non-repeating section into a
<template>
element. -
The
<body>
element is the main section of a report where you insert its core content.Figure 6. The <body> section is the main content of the report and sits in front of the <background>
<columns>
Splits either a report page or a table into columns.
Guidelines
<columns>
elements divide a page/table evenly into columns.
Use the <stack> element (discussed below) to stack the contents of <columns> top to bottom.
|
<body>
<columns>
<text>text 1</text>
<text>text 2</text>
</columns>
</body>
<table>
<columns>
<col width="50"/>
<col width="50"/>
</columns>
</table>
<stack>
Stacks the contents of an element vertically.
<text>
elements vertically in a <columns>
element.<columns>
<stack>
<text>text 1</text>
<text>text 2</text>
</stack>
</columns>
<styles>
Stores the style definitions for XML elements.
The <styles> element contains one or more <style> elements.
|
Guidelines
-
The
<styles>
element doesn’t display on report pages and is only used for style purposes. -
You must add
<style>
elements inside the<styles>
element to define the individual attributes for each style.
<styles>
<style name="center" fontSize="7" alignment="center"/>
<style name="header" bold="true" fontSize="15"/>
<style name="number" alignment="right"/>
<style name="tableFooter" fontSize="7" bold="true" color="#ffffff" fillColor="#308DE5"/>
<style name="tableHeader" fontSize="7" bold="true" color="#ffffff" fillColor="#003399"/>
<style name="tableSubhead" fontSize="7" bold="true" fillColor="#bfbfbf"/>
<style name="text" fontSize="7" alignment="left" />
</styles>
<style>
Stores the attributes for a style used to change the appearance of XML elements.
Attributes
Use XML attributes to control the appearance of <style>
elements.
<styles>
<style name="text" alignment="left" fontSize="7"/>
</styles>
Table Elements
<table>
Base element for a table.
Guidelines
Once you add a <table>
element, you can add other elements inside of it to build the table.
<table columnWidths="* *">
<tableHeader>
<row>
<cell>cell 1</cell>
<cell>cell 2</cell>
</row>
</tableHeader>
<tableBody>
<row>
<cell>cell 1</cell>
<cell>cell 2</cell>
</row>
</tableBody>
</table>
-
The
columnWidths
attribute sets the width for every column in the table. -
The
<tableHeader>
element inserts a repeating header. -
The
<tableBody>
element inserts a non-repeating table body. -
The
<row>
elements insert rows. -
The
<cell>
elements insert cells into the rows.
<table>
<columns>
<col width="*"/>
<col width="*"/>
</columns>
<tableHeader>
<row>
<cell>cell 1</cell>
<cell>cell 2</cell>
</row>
</tableHeader>
<tableBody>
<row>
<cell>cell 1</cell>
<cell>cell 2</cell>
</row>
</tableBody>
</table>
-
The
<columns>
element and thecol width
attributes inside it, set the width for every column in the table. -
The
<tableHeader>
element inserts a repeating header. -
The
<tableBody>
element inserts a non-repeating table body. -
The
<row>
elements insert rows. -
The
<cell>
elements insert cells into the rows.
<tableHeader>
Inserts a repeating header into a <table>
element.
<tableHeader> elements display at the top of a table on every page where the table displays.
|
<tableBody>
Inserts a non-repeating body section into a <table>
element.
<row>
Inserts a row into a <table>
.
Guidelines
<table> elements must contain <row> elements.
|
You can embed Each |
<table>
<table>
<tableBody>
<row>row 1</row>
<row>row 2</row>
</tableBody>
</table>
<cell>
Inserts a cell into the <row>
of a <table>
.
Guidelines
You must add Each |
<emptyCell>
Inserts an empty cell into the <row>
of a <table>
that contains no data
emptyCell
to leave a cell of a row blank, with no dataGuidelines
When you use the colSpan attribute to make a <cell> display across multiple columns, you must add <emptyCell> placeholders for each <cell> where you don’t want to display data.
|
<emptyCell>
elements into the <row>
of a <table>
.<row>
<cell style="text" alignment="right" colSpan="6">{{RecordType_DeveloperName}} Total</cell>
<emptyCell />
<emptyCell />
<emptyCell />
<emptyCell />
<emptyCell />
<cell style="number" bold="true">${{sum items "Extended_Amount__c"}}</cell>
</row>
This example uses the colSpan
attribute to merge the first six cells of the <row>
together.
When you use colSpan , you must add <emptyCell> placeholders for each empty cell you want to merge.
|
Image Elements
<images>
Stores the source code for images included on a report.
(Optional) Store the source code required to insert the contents of a long text area field.
Guidelines
You must add <image> elements inside the <images> element to define the source for each image.
|
<images>
<image name="companyLogo" src="data:image/png;base64,BASE64STRING"/>
</images>
Replace BASE64STRING with the base64 string for your image.
|
<images>
<image name="customerLogo" source="https://www.pexels.com/photo/gray-industrial-machine-during-golden-hour-162568/"/>
</images>
Replace "https://www.pexels.com/photo/gray-industrial-machine-during-golden-hour-162568/" with the URL for your online source. |
<images>
<image width='108' height='50.4'>{{FX5__Job__r.FX5__Office__r.Office_Logo__c}}</image>
</images>
<image>
Inserts an image or the contents of a long text area field
Image Sizing
Use the width
and height
attributes to define the size of <image>
elements.
Images resize to fit the dimensions specified for the <image>
element.
Remember the following when working with images:
-
72pt = 1 inch
-
300px = 1 inch
-
Add an
<image>
element in the exact place where you want the image to go<image name="companyLogo" width="144"/>
This element also stores the attributes for the image. -
Add a second
<image>
element inside the<images>
collection at the end of the template<images> <image name="companyLogo" src="data:image/png;base64,BASE64STRING"/> </images>
This element stores the source code for the image.
The name attribute links this element to the first <image> element.
|
Replace BASE64STRING with the base64 string for your image.
|
-
Add an
<image>
element in the exact place where you want the image to go<image name="customerLogo" width="144" marginLeft="40"/>
This element also stores the attributes for the image. -
Next, add a second
<image>
element inside an<images>
element at the end of the template<images> <image name="customerLogo" src="https://i.imgur.com/B3NJGly.jpg"/> </images>
This element stores the source code for the image.
The name attribute links this element to the first <image> element.
|
Replace "https://i.imgur.com/B3NJGly.jpg" with the URL for your image. |
<image width="144">data:image/png;base64,BASE64STRING</image>
This example places the base64 string directly into the template, without the need to reference the image source separately. |
Replace BASE64STRING with the base64 string for your image.
|
<image width='108' height='50.4'>{{FX5__Job__r.FX5__Office__r.Office_Logo__c}}</image>
<imageCapture>
Inserts an interactive image placeholder.
Use this placeholder to attach an image to a report, such as a photo or stamp.
You can also use the placeholder to attach an image already attached to the parent record. |
Guidelines
You can only insert .jpeg or .png images in the placeholder.
|
-
If you insert an image that has larger dimensions than the placeholder, the image resizes to fit the space.
-
When you attach an image to a report, the image also gets added as an attachment to the parent record.
<imageCapture id="Operator Stamp" caption="Operator Stamp" width="216" height="72">
<watermark rasterize="true">
<text color="gray" fontSize="20">{{FX5__Tracking_Number__c}}</text>
</watermark>
</imageCapture>
The id attribute serves as a unique identifier for the image placeholder.
|
<qr>
Generates a QR code for the specified content.
<qr fit="100">https://www.servicemax.com</qr>
The fit attribute sets the size of the QR code to 100pt.
|
Replace https://www.servicemax.com with the URL the user should go to with the QR code.
|
Signature Elements
<captureHeaderTemplate> Block
Use the <captureHeaderTemplate>
tag to insert lines of text on the signature capture page above the signature block.
This custom text displays in both FieldFX Mobile and FieldFX Back Office.
Use this with the <signatureBlock> element.
|
Guidelines
-
Place the
<captureHeaderTemplate>
just before the<signatureBlock>
element in the template. -
Include one or more
<captureHeaderRow></captureHeaderRow>
content rows within the opening and closing<captureHeaderTemplate>
tags -
Contents of the
<captureHeaderRow>
tag can use-
Standard XML formatting tags such as
<data>
,<formatDate>
, or<formatDateTime>
Attributes
-
<captureHeaderTemplate>
-
(Optional)
position
Valid values are
-
top
: Places the text block at the top of the screen.This is the default value if position
is not defined. -
right
: Floats the text block to the right of the screenFor example:
<captureHeaderTemplate position="right"> <captureHeaderRow>row contents</captureHeaderRow> </captureHeaderTemplate>
-
-
-
<captureHeaderRow>
-
label
: content to place in the left column of the block for the row -
value
: content to place in the right column of the block for the rowThe value
attribute is optional. You can instead place the XML elements or other contents for the right column between the opening and closing<captureHeaderRow>
tags.Example 31. Adding row contents in thevalue
attributeFor example:
<captureHeaderTemplate position="right"> <captureHeaderRow label="LOCATION" value="{{FX5__Office__r.Name}}"> </captureHeaderRow> </captureHeaderTemplate>
Example 32. Placing the right column content between opening and closing tagsFor example:
<captureHeaderTemplate> <captureHeaderRow label="LOCATION" > <data field="FX5__Office__r.Name"/> </captureHeaderRow> </captureHeaderTemplate>
-
Examples
<signatureCaptureTemplate>
block without using value
attribute<captureHeaderTemplate>
<captureHeaderRow label="JOB">
<data field="Name"/>
</captureHeaderRow>
<captureHeaderRow label="CUSTOMER" >
<data field="FX5__CustomerAccount__r.Name"/>
</captureHeaderRow>
<captureHeaderRow label="LOCATION" >
<data field="FX5__Office__r.Name"/>
</captureHeaderRow>
<captureHeaderRow label="PRICE BOOK" >
<data field="FX5__Price_Book__r.Name"/>
</captureHeaderRow>
<captureHeaderRow label="WORK START" >
<formatDateTime field="FX5__Actual_Start_Date__c" format="MM/DD/YY h:mm A"/>
</captureHeaderRow>
<captureHeaderRow label="WORK END" >
<formatDateTime field="FX5__Actual_End_Date__c" format="MM/DD/YY h:mm A"/>
</captureHeaderRow>
</captureHeaderTemplate>
<signatureCaptureTemplate>
block with content in the value
attribute<captureHeaderTemplate position="right">
<captureHeaderRow label="JOB" value="{{Name}}" />
<captureHeaderRow label="CUSTOMER" value="{{FX5__CustomerAccount__r.Name}}" />
<captureHeaderRow label="LOCATION" value="{{FX5__Office__r.Name}}" />
<captureHeaderRow label="PRICE BOOK" value="{{FX5__Price_Book__r.Name}}" />
<captureHeaderRow label="WORK START" value="{{formatDateTime FX5__Actual_Start_Date__c format="MM/DD/YY h:mm A"/}}" />
<captureHeaderRow label="WORK END" value="{{formatDateTime FX5__Actual_End_Date__c format="MM/DD/YY h:mm A"/}}" />
</captureHeaderTemplate>
<signatureBlock>
Inserts an interactive signature line.
Use this signature line to capture digital signatures on reports. |
Guidelines
If you insert an image that has larger dimensions than the placeholder, the image resizes to fit the space. |
<signatureBlock id="Company Man Signature" caption="Company Man Signature" width="220" height="50">
<watermark>data:image/png;base64,BASE64STRING"</watermark>
</signatureBlock>
The id attribute serves as a unique identifier for the signature line.The caption attribute makes the signature line display available for completion when attaching the report to a record.
|
If you are inserting multiple signature lines, use a field as the unique identifier for each signature line.
For example,
[]`signatureBlock id="{{FX5__SyncID__c}}"`
The <watermark> element inserts a visual indicator so users know where to add signatures, such as the blue shading in the following example:The <watermark> element is discussed in this article. |
<watermark>
Inserts an image into a <signatureBlock>
element.
Use to add a visual indicator so users know where to add signatures. |
Guidelines
To use an image, you must encode the image to a base64 string and enter the string in the You can only insert |
Image Sizing
Remember the following when working with images:
-
72pt = 1 inch
-
300px = 1 inch
Images resize to fit the dimensions specified for the <signatureBlock> element.
|
If you insert a 900px wide image and set the width for the <signatureBlock> element to 144pt, the image resizes to 600px wide.
Attributes
You can add the following special attributes to a <watermark>
element:
-
Add a
<watermark>
element inside the<signatureBlock>
element<signatureBlock id="customerSignature" width="216" height="72"> <watermark name="watermark"></watermark> </signatureBlock>
-
Add a second
<watermark>
element inside the<images>
collection at the end of the template.<images> <image name="watermark" src="data:image/png;base64,/9j/4AAQSkZJRgABAQEAYABgAAD..."/> </images>
User your own image’s base64 encoding instead of the encoding in this example. |
This element stores the source code for the signature line image. |
The name attribute links this element to the first <watermark> element.Remember, spaces are not allowed in the `name `attribute. |
<signatureBlock id="customerSignature" width="216" height="72">
<watermark>data:image/png;base64,/9j/4AAQSkZJRgABAQEAYABgAAD/...==</watermark>
</signatureBlock>
Text Elements
<text>
Inserts text.
Guidelines
-
You can use spaces and line breaks inside of
<text>
elements. -
You can also add
<text>
elements inside other<text>
elements. -
When using
<text>
elements inside<cell>
elements, all text must be enclosed in a<text>
element.
<text>As the representative for the company listed above, I acknowledge that the work performed has been done in a professional and acceptable manner. I also understand that the amounts for which I am signing are not the final invoiced amounts. Final invoice amounts will include, if applicable, any required Federal, State, County, and Local taxes along with any outstanding third party charges.</text>
Replace the language with your company’s approved message. |
<textTransform>
Inserts specially formatted text.
<cell rowSpan="2"><textTransform rotate="270" fontSize="7">CLIENT INFO</textTransform></cell>
This example uses the rowSpan attribute to merge two rows and display the rotated text across both rows.The rotate attribute rotates the text 270 degrees.
|
<rtf>
Inserts the contents of a long text area or rich text area field.
Limitations
When you embed an image in a rich text area field, the image only displays on a report if:
|
The following tags are |
|
The conversion to PDF may result in unexpected results. Always test your reports. |
<rtf maxImageSize="300"><![CDATA[{{{FX5__Job__r.Job_Photos__c}}}]]></rtf>
You must use triple curly brackets {{{ }}} for expressions inside the <rtf> element.
|
The maxImageSize attribute downsizes images proportionately to have a height or width no greater than 300pt.
|