Document Templates

NOTES:

• Deleting or moving a inPoint template-document does not touch the template definition. So you have to delete the template separately after deleting the document. Also if you delete the template the template-document is not touched.

• Moving ore deleting a template-document accidentally results in a non working template because the link from the template to the template-document is broken (the ItemURI does not longer reference the document). To fix this move the document back to it's previous folder (or undelete it from the recycle-bin) or delete also the template manually.

Template engines

There are two templates engines in inPoint available. The Tokenizer engine supports only some simple predefined patterns while the Scriban engine supports patterns and code blocks to calculate values.

For calculating the file name for a document created by a template always the Tokenizer engine is used. For the template document itself both engines can be used.

Both template engines have a different configuration and syntax but both are listed in one list when creating documents from templates or configuring the DocTemplate plugin.

For Tokenizer templates the name should be distinct because it is needed to locate a template. When using the DocTemplates plugin also beware not to change the names of the templates because this can break the configurations of the plugins.

Scriban templates use an internal id so having templates with identical names produces no problems (except for confusing the user when listing them in the one list)

Tokenizer templates

Configuration for Tokenizer templates

The configuration is done by the text file doctemplates.txt in the plugin folder on the inPoint.Server. It looks like:

<?xml version="1.0"?>
<DocTemplates xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

  <Template name="template1" isDefault="true">
    <templatePath>TEMPLATE1.docx</templatePath>
    <description>Template One</description>
	<icon>pack://application:,,,/inPoint.Resources;Component/Icons/doc_32.png</icon>
    <documentName>{folder.autoid.2.++}.docx</documentName>
 </Template>

</DocTemplates>

This examples defines one template by a name and a description. It is marked as Default-Template (see DocTemplates plugin) and the content is in the file TEMPLATE1.docx. This file is also loaded from the plugin folder. For the document name (this is the suggested name when creating a document from this template) an expression was specified.

NOTE: When using text files ensure that they contain only 7-ASCI or save the file with UTF-8 encoding (with or without BOM). Otherwise some characters are lost after the conversion!

See also: Restrictions and workarounds for text documents

Formatting Tokenizer templates

Each pattern must start with a single { and end with a single }. Available patterns are:

Pattern	Description
{user}	Current user's fullname
{date}	Current date
{docname}	Filename
{folder.*}	Any of the Folder attributes (exact case match)
{doc.*}	Any of the Document attributes (exact case match) - useful only for emails since doc has already been archived
{field.*}	Field values e.g. {field.*.key} or {field.*.value}
{file.*}	Attachment files {file.count}, {file.name}

There is also an auto increment pattern like:

<documentName>MyDocument_{folder.autoid.2.++}.docx</documentName>

In this example the value from the folder field autoid is used and formatted with 2 digits. Afterwards the value of the folder field autoid is increased by one.

There are also some special Placeholders names for Emails: {MAIL_SUBJECT}, {MAIL_TO}, {MAIL_CC}, {MAIL_BCC} and {MAIL_BODY}

Using Tokenizer templates

In inPoint.Client you can right click on a folder and run the command action DocumentCreateFromTemplate "New Document from Template".

Select one document from the list, enter a new file name (or keep the suggested file) and create the new document. You can also click "Edit" but for this templates configured in the doctemplates.txt you cannot edit anything. At least you can click "Preview" to get a rendered Template without archiving the created document to inPoint.

Supported file types for Tokenizer templates

All files types are supported - they are just loaded as text. But special support is there for the Office file formats .docx, .xlsx and .pptx.

NOTE: Only OpenXml documents can be used but not the old office binary formats (like .doc, .xls or .ppt)

Scriban templates

Configuration for Scriban templates

The configuration is stored in the database table IP_DOCTEMPLATE. This table is managed by the command ConvertToDocTemplate "Create or edit template".

Right clicking a document which is no template document yet and running the ConvertToDocTemplate action creates a templates definition for this document and adds an entry into the IP_DOCTEMPLATE.

Right clicking a document which is already a template document and running the ConvertToDocTemplate action lets you edit some settings in the IP_DOCTEMPLATE. You can also delete the template definition from the IP_DOCTEMPLATE (which does not delete the document itself)

Left-clicking the DocTemplate icon also opens the settings window.

For new templates you can choose an ID (or keep the suggested one), Name, Description and a Document Name, which is a suggestion for the name when creating a document from this template. the Document Name can also contain some patterns and is processed by the Tokenizer engine. You can also choose an icon to be shown in the "Create Document from Template"-Window:

• System default: This shows the icon from the currently installed application.
• Predefined: Select one of the predefined inPoint icons
• Custom: enter any file extension ad the icon from this associated extension will we shown

Default: If you mark this template as an Default-Template the template will be available in all "Create Document from Template"-Windows when no DocTemplate plugin is used. (see DocTemplates plugin)

Formatting Scriban templates

The patterns are no longer just fixed patterns like for the Tokenizer engine but code blocks which are evaluated with predefined values. The blocks have to be in double curly brackets. If you enter invalid expressions and click the "Preview" button you get a detailed error message instead of the rendered document.

Example #1:

Document with content: {{a*/5}}*}}

Click "Preview" and you get:

Error rendering the template "newDoc.txt":

Location: CreateDocument.BuildContext
Types: Infos
Message 001 info: Known pattern: {{date}}=2020-10-18T22:00:00.0000000Z
        002 info: Known pattern: {{docname}}="newDoc.txt"
        003 info: Known pattern: {{user}}="rsr (Schröttner Robert)"
        004 info: Known pattern: {{folder.name}}=TEST
...
        053 info: Known pattern: {{file.file.creationtime}}=2020-10-19T13:22:49.4244291Z
        054 info: Known pattern: {{file.file.creationtimeutc}}=2020-10-19T13:22:49.4244291Z
        055 info: Known pattern: {{file.file.lastwritetime}}=2020-10-19T13:22:49.4462067Z
...
Location: CreateDocument.ParsingTextFile
Types: Errors
Content 0001 {{a*/5}}
Message 001 error(<input> Ln:1 Col:5): Error while parsing binary expression: Expecting an <expression> to the right of the operator instead of `Divide` in: <expression> operator <expression>

So you get the error CreateDocument.ParsingTextFile which tells you the expression with the error and usually also a human readable reason.

Additionally you get the warning CreateDocument.BuildContext which shows you all the available variables with their values.

When designing the document you can use the steps:

• Use "Open" button for editing the templates document
• Save the changes (and wait for inPoint.Sync to upload the changes)
• Click "Preview" to render the document.

Example #2:

Document with content:

calculated constant {{ 13*57/2 }}
from pattern {{docname}}
calculated from pattern {{ docname | string.size * 10 }}

Click "Preview" and you get:

calculated constant 370.5
from pattern newDoc.txt
calculated from pattern 100

For detailed informations about the Scriban language see: https://github.com/scriban/scriban/blob/master/doc/builtins.md

Using Scriban templates

In inPoint.Client you can right click on a folder and run the command action DocumentCreateFromTemplate "New Document from Template".

Select one document from the list, enter a new file name (or keep the suggested file) and create the new document. You can also click "Edit". In the Edit Window you can create a "Preview" to get a rendered Template without archiving the created document to inPoint or just "Edit" the template document.

Supported file types for Scriban templates

The supported file extensions are .docx, .xlsx, .pptx, .txt, .htm and .html The file types that are working without any troubles are .txt, .htm and .html.

For the office file formats maybe the workaround is needed.

See also: Restrictions and Workarounds for office documents

NOTE: When using text files ensure that they contain only 7-ASCI or save the file with UTF-8 encoding (with or without BOM). Otherwise some characters are lost after the conversion!

See also: Restrictions and workarounds for text documents.

DocTemplates plugin

The plugin can be added to the folder format. If specified you can configure which templates are provided when creating documents in this folder. For all folders without the plugin all templates which are marked as "Default Template" are listed.

The plugin stores the selected templates by it's id. For templates read form the IP_DOCTEMPLATE the id is created on creation and cannot be changed later. So you can change the DocTemplate name without affecting the configurations of any DocTemplate plugin.

When DocTemplates are defined in doctemplates.txt there is no id. Instead the Name is used by the DocTemplate plugin. Therefore you should never change a name in this templates or you might break the configurations of existing DocTemplate plugins.

Restrictions and Workarounds

Text documents

If you lost some characters after conversion (typically umlauts like ÖÄÜ are incorrectly rendered) verify that the templates document is saved with UTF-8 encoding (with or without BOM)

In WordPad, File / SaveAs / Encoding select:

Encoding
ANSI	Only works when having characters from 7-bit ASCI
UTF-8	Works! This is the recommended encoding
UTF-8 with BOM	Works!
UTF-16 LE	Works!
UTF-16 BE	Works!

The rendered document is always UTF-8 with BOM encoded.

Office documents

Sometimes the pattern written in office are not saved as-is into the document. Office might insert some non visible control statements in between. So when a pattern is not working first inspect the saved text:

• An OpenXML file is just a document/folder structure packed with ZIP
• Open the OpenXML file with any ZIP-Tool (or unpack the contents)
• Locate and open the content file. For .docx files this can be word\document.xml
• Fix the content
• Put the changed document.xml back into the ZIP
• Verify that the document can be still opened with office and the changed content is still there

Example for fixing the content in the document.xml:

• Word document content: {user}
• Content in the document.xml:

 <w:r><w:tab/><w:t> { </w:t></w:r>
 <w:proofErr w:type="gramStart"/> <w:r><w:t> user </w:t></w:r> <w:proofErr w:type="gramEnd"/>
 <w:r><w:t> } </w:t></w:r>

• This block should then be replaced by {user}.

NOTE: Ensure that you do not remove any XML-begin block without also removing the XML-end block!