Lightning Tools Knowledge Base

Lightning Forms

Actions

Document Generator

Detailed documentation for the Generate Document action in Lightning Forms and Lightning List Actions

Table of contents

What is Document Generator
Configuration UI
Document Templates
- Example of a template
- Word Generator Placeholder Expressions
  - Expression syntax
- Placeholders usage details

What is Document Generator

"Document Generator" allows you to generate documents based on a standard Microsoft Word file filled with SharePoint list data.

This can be triggered in actions used in List Actions or Modern Forms.

The generated document can either be downloaded directly in the browser or be stored in a SharePoint library.

Main advantages:

Word Document is generated on a fully customizable template
Creating a template is as simple as writing a word document and can be done by power users
Metadata of a single item, a list or even connected sublists with all their data can be added into this document
Report across a dossier (master-slave relation) can be created

The Document Generator feature provides the ability to generate different types of documents, such as:

Invoice
Factsheet
Project Report
Correspondence
Work Report
Order Confirmation
Inventory List
... and many more

Configuration UI

Configuration for a single item (example: Command Bar Action on a Display Form):

Configuration for multiple items (example: List Action on a View):

Description of the configuration parameters:

Template
- Provided Word Template that contains placeholders can be uploaded here (templates are stored in a hidden library "sbDocumentGenerator")
  The current used template can be downloaded by clicking on the “Current template” link.
Data
- Choice: “For single item” / “For multiple items”
- List: list from current site
- Item ID (only if “For single item” selected): ID or expression to be evaluated as ID of the item we want to have as context in the document
- List Query (only if “For multiple items” selected): CAML query used to filter list item
- List View (only if “For multiple items” selected): defined filters in list views are merged with the query above
Target
- Choice: “Save to library” / “Open in browser”
- Library (only if “Save to library” selected): target document library, where the generated document should be stored
- Subfolder (only if “Save to library” selected): fixed subfolder path or dynamically calculated using an expression e.g. with placeholders
- Filename: file name for generated document. fixed name or dynamically calculated using an expression e.g. with placeholders
- Overwrite Existing File (only if “Save to library” selected): if checked and the file is already stored in the configured library, the old file will be overwritten.

Document Templates

Supported template format is docx. The template is created in Microsoft Word or other software that support the docx format.
Currently Document Generator allows inserting Lightning Forms placeholders, conditions, loops, nested loops and loops over table rows.

In the next versions also insertion of images will be possible.

Example of a template

Find the generate link on the "Work hours for week" dossier display form:

Example of generated document

Word Generator Placeholder Expressions

You can use different kinds of expressions to show the metadata in a word document.

Expression syntax

Template expressions

Any kind of string Template Expression

[[Title]] [[Firstname]]

Assignment Expressions

Start with "[[=" and any kind of string Expression

[[= [[Title]] + ", " + [[Firstname]] ]]

Function Code Expressions

Start with "[[{" in the Tag property. Write your complex expression as content in the placeholder

[[{ var arr = [[@Loop('Invoice', [[{ return [[Total]]; }]] )]]; var sum = 0; arr.forEach(n=>sum +=n); return sum; }]]

Lookup Values

Use the [[Lookup.FieldInternalName]] notation to get any value from the target list of a lookup

[[Department.Code]]

[[Department.Author]]

-------------------------------------------------------------

[[Department.Key]] -> to get the item ID of the department

If Conditions

Start with [[if …]] and any kind of boolean Expression (Condition).
Ends with [[end if]]

Everything between the starting and the ending tag will be visible if the condition is true. This can be a text, an image etc.

[[if [[Budget]] > [[Outgoings]] ]]

[[Title]]

[[end if]]

-------------------------------------------------------------

[[if {return ([[Budget]] > [[Outgoings]]);} ]]

[[Title]]

[[end if]]

-------------------------------------------------------------

[[if [[Status]]!="Completed" ]]

[[Title]]

[[end if]]

Loops

Start with [[loop]] for looping over multiple items of selected list.

If CAML Query is configured for this action link, looping will be filtered according to it.

Start with [[loop SublistTitle]] for looping over the sublist items filtered by lookup to the parent list.

Use filterlookupfield('field_internal_name') param to specify which lookup field to use for sublist in a case when several lookups on the same list exist. It's optional where there is just one lookup field.

Also RowLimit is hardcoded for 200 items for query, but needed number can be specified with optional rowlimit(number) param.

If list that is not a sublist is selected (doesn’t have lookup to the list selected in action link configuration), no filtering will be applied.

Iteration ends with [[end loop]]

[[loop]]

[[Title]]

[[end loop]]

-------------------------------------------------------------

[[loop SubListTitle filterlookupfield('field_internal_name') rowlimit(number)]]

[[Title]]

[[Firstname]]

[[end loop]]

Filtered Loops

Where 'SomeView' is a view .aspx page title:

The order and filter of the view are applied. If CAML query is added (optional), it is united with view query using an 'and' operator.

[[loop SublistTitle view('SomeView') query('<Where><BeginsWith><FieldRef Name="Title" /><Value Type="Text">[[{return [[Title]];}]]</Value></BeginsWith></Where>')]]

[[Title]]

[[end loop]]

Loops over documents in sublibraries

Use the Scope="Recursive" property on the query to get documents in a folder, when used as sublibrary of a dossier.

Combine recursive scope and filter in CAML query to filter the listed document's metadata.

[[loop SublibraryName query('<View Scope="Recursive"></View>')]]

[[FileLeafRef]]

[[Title]]

[[OtherField]]

[[end loop]]

-------------------------------------------------------------

[[loop SublibraryName query('<View Scope="Recursive"><Query><Where><Eq><FieldRef Name="IsActive" /><Value Type="Boolean">1</Value></Eq></Where><OrderBy></OrderBy></Query></View>')]]

[[FileLeafRef]]

[[Title]]

[[OtherField]]

[[end loop]]

Nested Loops

Looping over sublist inside of the loop over multiple items of parent list is supported.
Looping over several sublists, or sublist of sublist are supported as well.

[[loop]]

[[Title]]

[[loop SubList1]]

[[Title]]

[[Firstname]]

[[end loop]]

[[loop SubList2]]

[[Title]]

[[Firstname]]

[[end loop]]

-------------------------------------------------------------

[[loop]]

[[Title]]

[[loop SubList]]

[[Title]]

[[Firstname]]

[[loop SublistOfSublist]]

[[Title]]

[[end loop]]

Loops over table rows

It is possible to loop over table rows by adding the loop inside the table.

In case of nested loops, if loop on parent list is placed into the external table, this will render separate table for each parent item

[[loop

SubListTitle]]

[[Title]]

[[Firstname]]

[[Lastname]]

[[end loop]]

[[loop]] [[Title]]

[[loop

SubListTitle]]

[[Title]]

[[Firstname]]

[[Lastname]]

[[end loop]]

Image

Show an image inside the document

You can optionally specify the static width and height of the image and also max/min width and height

Width/height parameters are not mandatory, can be string empty '' or null.

[[image ([[Picture]], width, height, maxwidth, maxheight, minwidth, minheight)]]

Without width and height:

[[image ([[Picture]])]]

Static width and height numbers used:

[[image ([[Picture]], 50, 50)]]

Static width number used:

[[image ([[Picture]], 20)]]

Static height number used:

[[image ([[Picture]],,150)]]

[[image ([[Picture]], '', '', 100, 300)]]

[[image ([[Picture]], maxwidth=100, maxheight=300)]]

[[image (url=[[Picture]], maxwidth=100, maxheight=300)]]

Placeholders usage details

The following placeholders from the Expression builder can be used in the word template:

Form Fields placeholders (except of [[..IsChanged]] and [[..OriginalValue]]
Web placeholders, including functions for filtering with CAML Query
Site placeholders, including functions for filtering with CAML Query

Not supported for usage in document generation:

Form Fields [[..IsChanged]] and [[..OriginalValue]] placeholders
Form placeholders
Functions placeholders
Page placeholders
User placeholders
Sublist placeholders

Published Sept 25, 2022