The SnippetResolver can be used to insert texts into a document. The texts can be specified in different ways:

Basically all variants follow the same scheme: You pass the content and define via a bookmark in the template where this content will be inserted. The number of snippets is unlimited. Content that was stored in the bookmark during template creation is replaced with the new content.

note

NOTE
The corresponding template must have the SnippetResolver ("Snippets") document function attached.

NOTE
The corresponding template must have the SnippetResolver ("Snippets") document function attached.

Quick parts

The "SnippetResolver" also undertakes another function. primedocs snippets can be added to the generated template as "AutoText" or "Quick parts". The "AutoText" snippets included this way are then available as normal quick snippets in Microsoft Word.

In the standard case, all "AutoText" snippets available to the user are automatically stored. This behavior can be overridden via the configuration in the document function or in Connect using this setting:

<?xml version="1.0" encoding="UTF-8"?>
<OneOffixxConnectBatch xmlns="http://schema.oneoffixx.com/OneOffixxConnectBatch/1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Entries>
    <OneOffixxConnect>
      <Arguments>
        ...
      </Arguments>
      <Function name="SnippetsResolver" id="dd752747-733e-4175-9fc7-028ab7472742">
	    <Settings>
			<Value key="AutoTextDisabled">true</Value>
		</Settings>
        <Arguments>
          ...
        </Arguments>
      </Function>
    </OneOffixxConnect>
  </Entries>
</OneOffixxConnectBatch>

primedocs snippets

A scenario: A new document is to be created and filled with snippets. The id of the snippet can be read out with the help of the snippet editor. Each id is unique and does not change after creation. The language is defined via the document language.

<?xml version="1.0" encoding="UTF-8"?>
<OneOffixxConnectBatch xmlns="http://schema.oneoffixx.com/OneOffixxConnectBatch/1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Entries>
    <OneOffixxConnect>
      <Arguments>
        <TemplateId>6bb49520-1ebd-4f68-bb5f-02f46a9e1ec8</TemplateId>
        <LanguageLcid>2055</LanguageLcid>
      </Arguments>
      <Function name="SnippetsResolver" id="dd752747-733e-4175-9fc7-028ab7472742">
        <Arguments>
          <Snippet id="A7835D23-E945-4A39-81B9-3CEC067E26C0" bookmark="Bookmark1" />
          <Snippet id="B8235D23-D945-5A39-31B9-23EC067E2120" bookmark="Bookmark1" />
          <Snippet id="43535D23-45D5-6A39-81B9-DE1C067E2112" bookmark="Bookmark2" />
          <Snippet id="XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" bookmark="Bookmark3" />
        </Arguments>
      </Function>
    </OneOffixxConnect>
  </Entries>
</OneOffixxConnectBatch>

Several snippets can be grouped in one bookmark (e.g. "Bookmark1") by using the same name in the "Bookmark" attribute. The snippets are inserted in the same order as they appear in the XML. It is also possible to use the "_OneOffixxOpenAt" bookmark. This will insert the text at the cursor's position defined in the primedocs template.

External "Text" snippets

If you want to pass unformatted text content from a specialist application, you can do it like that:

<?xml version="1.0" encoding="UTF-8"?>
<OneOffixxConnectBatch xmlns="http://schema.oneoffixx.com/OneOffixxConnectBatch/1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Entries>
    <OneOffixxConnect>
      <Arguments>
        <TemplateId>6bb49520-1ebd-4f68-bb5f-02f46a9e1ec8</TemplateId>
        <LanguageLcid>2055</LanguageLcid>
      </Arguments>
      <Function name="SnippetsResolver" id="dd752747-733e-4175-9fc7-028ab7472742">
        <Arguments>
          <Snippet bookmark="Bookmark3">
            Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Maecenas porttitor congue massa. Fusce posuere, magna sed pulvinar ultricies, purus lectus malesuada libero, sit amet commodo magna eros quis urna.
            Nunc viverra imperdiet enim. Fusce est. Vivamus a tellus.
            Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Proin pharetra nonummy pede. Mauris et orci.
            Aenean nec lorem. In porttitor. Donec laoreet nonummy augue.
            Suspendisse dui purus, scelerisque at, vulputate vitae, pretium mattis, nunc. Mauris eget neque at sem venenatis eleifend. Ut nonummy.
          </Snippet>
        </Arguments>
      </Function>
    </OneOffixxConnect>
  </Entries>
</OneOffixxConnectBatch>

External "HTML" snippets

To insert formatted content into the document it is recommended to pass the content as "HTML" snippet. primedocs provides its own HTML parser and also recognizes primedocs custom attributes to translate style and formatting options directly into OpenXML properties.

Basic structure

The structure is almost identical, but an additional parameter "parser" has been added to the snippet. In the "parser" "primedocs" must be specified.

<Snippet bookmark="_OneOffixxOpenAt" type="Html" parser="primedocs">
	<![CDATA[
  		<p>HTML Fragments...</p>
	]]>
</Snippet>

primedocs attributes

To pass style or "rendering" information, the following attributes can be used:

IMPORTANT
Only existing styles can be used, i.e. these must exist in the Wordprocessing document respectively in the style template. In addition, the 'StyleId' is used, which may differ from the displayed name in Microsoft Word. (e.g. from 'Heading 1' Office can create a style with the Id 'Heading1').
If a style is used with a list, this is only applied if 'listing formatting' is defined at this style.

NOTE

About CSS and other attributes:
CSS specifications or attributes are ignored (except for "colspan" for table and "src" for images).

About text specifications:
The parser can convert both UTF8 and HTML encoded (e.g. ü) texts directly into Open XML. Exceptions to this are the following characters, which must be encoded in HTML:

  • " als &quot;
' als &apos;
> als &gt;
< als &lt;
& als &amp;

Typography elements

These elements are converted to the corresponding OpenXML elements. An attempt is made to adhere to the respective style, so that a <b> is formatted "bold" accordingly.

Elements for OpenXML paragraphs:

Elements for OpenXML text:

Elements for OpenXML lines:

Elements for OpenXML line, column or page breaks:

Elements in which known child elements are searched:

Nested <p> or <h1> (etc.) elements are not supported. These elements are also not designed for this according to the HTML specification.

WARNING
<h1>-<h6> elements are treated like <p> elements, but no Word style is automatically applied. Styles must always be specified explicitly.

Image elements

Images can be transmitted as Data URI scheme.

Elements:

Supported image formats (specified by the MIME type in the data URL) are:

primedocs attributes:

Images can be used in continuous text, as a single paragraph, in lists or tables.

There are different options for the calculation of the image size:

Optionally, the "data-oo-image-title" and "data-oo-image-desc" can be used to store descriptions in OpenXML.

Table elements

HTML tables can also be converted, but without style specification, which will be discussed later, no table borders or similar are displayed.

Elements:

The "colspan" attribute applies to <td> elements.

primedocs attributes:

NOTE
Percentages or absolute cm or dxa (twips) values:
Percentages can lead to incorrectly displayed documents in connection with the ConvertToPdf command. If absolute specifications are used, AutoFit is not available.

Input control elements

Certain HTML input controls can also be converted to the respective Open XML "custom control".

Elements:

These controls can be placed individually as well as in the normal text flow.

List elements

HTML lists can also be converted, but they will only be provided with minimal style specifications if no explicit style is specified.

Elements:

Note on Word lists and paragraph styles:

Lists are controlled in Word by two different types of "Word styles", i.e. styles. There are "list types" which control indentation, characters and numbering (e.g. the numbers 1. and 1.1 and 1.1.1). This list type can have a different style attached to it, which affects the actual text next to the numbering specification. In order for primedocs to convert the HTML list correctly, the following procedure should be followed:

For each "main" '<ul>' resp. '<ol>' one list type should be defined. This list type should be connected with a style (e.g. "ListText"). In the connect only the name of the actual style (e.g. as above "ListText") is specified – the list type is indirectly linked. Currently it is necessary to specify the style on each new "<ul>" resp. "<ol>" layer. It is also possible to use different styles. Without specification Word uses the default paragraph style.

Summary:

You can create any number of styles to format the text in a list. This must be specified at each level. A list type which is associated with the "primary" style must be created. This list type controls the numbering, indentations, etc.

Example

<Snippet bookmark="_OneOffixxOpenAt" type="Html" parser="primedocs">
<![CDATA[
  <p>HTML Fragments...</p>
  <p></p>
  <ul data-oo-style="CorpList">
    <li>Element one</li>
    <li>
      <ul data-oo-style="CorpList">
        <li>Below element</li>
      </ul>
    </li>
  </ul>
  <p data-oo-style="Highlight">Text</p>
  <p>
    <u>
      <em>
        <strong>bold, italic and underlined</strong>
      </em>
    </u> or without</p>
  <p>Table with cm-Values:</p>
  <table data-oo-style="ListTable3Accent5" data-oo-table-columns="2cm,10cm" width="100%">
    <tr>
      <td>first column</td>
      <td>second column</td>
    </tr>
    <tr>
      <td>foo</td>
      <td>bar</td>
    </tr>
    <tr>
      <td>foo</td>
      <td>bar</td>
    </tr>
  </table>
  <p>Table with Pct:</p>
  <table data-oo-style="ListTable3Accent5" data-oo-table-width="70" data-oo-table-columns="20,80" width="100%">
    <tr>
      <td>first column</td>
      <td>second column</td>
    </tr>
    <tr>
      <td>foo</td>
      <td>bar</td>
    </tr>
    <tr>
      <td>foo</td>
      <td>bar</td>
    </tr>
  </table>
  <img data-oo-image-title="Test-Title" data-oo-image-desc="Test description" data-oo-image-width="50" data-oo-image-sizeunit="px" src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAIAAAD91JpzAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAAAYdEVYdFNvZnR3YXJlAHBhaW50Lm5ldCA0LjAuOWwzfk4AAAAWSURBVBhXY/gvwFD734Lhv9r//491ASz+Bve3zck6AAAAAElFTkSuQmCC" />
  <p>
    <span>Last...</span>
  </p>
]]>
</Snippet>

External "Office HTML" snippets

When submitting HTML content, the "type" Html must be specified. In general, all HTML content permitted by Microsoft Office can be submitted.

CAUTION
Microsoft Office recognizes HTML elements to a limited extent and can integrate them into Word with the appropriate formatting. However, it is recommended to use the primedocs HTML Parser to get styling information.

Simple texts:

<Snippet bookmark="_OneOffixxOpenAt" type="Html">
    <![CDATA[
            <p>Demo</p>
    ]]>
</Snippet>

Texts in defined Word style:

Headings like H1-H4 as well as the normal formatting (e.g. bold resp. <strong>) are automatically displayed in the corresponding heading style (e.g. <h1> = Heading1).

<Snippet bookmark="_OneOffixxOpenAt" type="Html">
  <![CDATA[
  <h1>Large title</h1>
  <strong>bold text</strong>
  ]]>
</Snippet>

Texts can be assigned to a specific Word style by specifying "mso-style-name:".

<Snippet bookmark="_OneOffixxOpenAt" type="Html">
  <![CDATA[
    <p style="mso-style-name:oneoffixxStyleName">Demo</p>
  ]]>
</Snippet>

Tables:

Tables can also be transmitted as HTML.

<Snippet bookmark="_OneOffixxOpenAt" type="Html">
  <![CDATA[
      <table width="100%">
          <tr>
            <td>erste Spalte</td>
            <td>zweite Spalte</td>
          </tr>
      </table>
  ]]>
</Snippet>

Images:

Images can be transmitted as Data URI.

<Snippet bookmark="_OneOffixxOpenAt" type="Html">
  <![CDATA[
      <img src="data:image/png;base64,..."
  ]]>
</Snippet>

External "FlatOPC" snippets

Snippets in Flat OPC format can also be accepted. However, no styles or numberings are accepted, but only the body part. This option should only be used in exceptional cases, since the primedocs HTML Parser can handle style information and is therefore the better choice.

<Snippet bookmark="_OneOffixxOpenAt" type="OpenXml">
  <![CDATA[
    <?mso-application progid="Word.Document"?>
    <pkg:package xmlns:pkg="http://schemas.microsoft.com/office/2006/xmlPackage">
    ...
    </pkg:package>
  ]]>
</Snippet>