SnippetResolver

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

  • OneOffixx internal snippets can be specified via their id.
  • OneOffixx external snippets can be transmitted in text or HTML format.
  • The content can be transferred in OPC flat format.

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

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

Quick parts

The "SnippetResolver" also undertakes another function. OneOffixx 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>

OneOffixx 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 OneOffixx 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. OneOffixx provides its own HTML parser and also recognizes OneOffixx 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" "OneOffixx" must be specified.

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

OneOffixx attributes

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

  • data-oo-style: The specified style will be applied to the corresponding Open-XML element.
    • Styles can be applied to <p>, <ul> / <ol> oder <table> elements.
  • data-oo-align: defines the alignment.
    • Possible values: left, right, center
    • The attribute can be applied to <p>, <td> oder <th> elements.
  • data-oo-table-...: defined specifications for <table> elements.
  • data-oo-image-...: defined specifications for <img> elements.
  • data-oo-background: Defines a background color.
    • Possible values: HEX color codes, e.g. E2001A
    • The attribute can be applied to paragraph (<p>, <h1>, etc.), <td> or <th>, or text (<span>, <strong>, etc.) elements.
  • data-oo-foreground: defines a font color.
    • Possible values: HEX color codes, e.g. E2001A
    • The attribute can be applied to paragraph text (<span>, <strong>, etc.) elements.
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).

Note 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:

" as &quot;
' as &apos;
> as &gt;
< as &lt;
& as &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:

  • <p>
  • <h1>, <h2>, <h3>, <h4>, <h5>, <h6>
  • <pre>,<blockquote>,<address>

Elements for OpenXML text:

  • <span>
  • <u>
  • <s>
  • <sub>
  • <sup>
  • <i>
  • <em>
  • <b>
  • <strong>
  • <code>,<time>,<label>
  • <a> (only the link text is applied)

Elements for OpenXML lines:

  • <hr>
    • Optional attributes:
      • data-oo-hr-type="---": Creates a line similar to AutoFormat "---"
      • data-oo-hr-type="___": Creates a line similar to AutoFormat "___"
      • data-oo-hr-type="###": Creates a line similar to AutoFormat "###"
      • data-oo-hr-type="~~~": Creates a line similar to AutoFormat "~~~"
      • data-oo-hr-type="***": Creates a line similar to AutoFormat "***"
      • data-oo-hr-type="===": Creates a line similar to AutoFormat "==="
    • Without attribute specification a line element is created.

Elements for OpenXML line, column or page breaks:

  • <br>
    • Optional attributes:
      • data-oo-br-type="textWrapping": Creates a line break.
      • data-oo-br-type="page": Creates a page break.
      • data-oo-br-type="column": Creates a column break if the section contains multiple columns.
    • Without attribute specification a normal line break is generated.

Elements in which known child elements are searched:

  • <html>,<body>,<form>,<div>

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:

  • <img>

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

  • image/bmp
  • image/png
  • image/gif
  • image/jpeg
  • image/tiff

OneOffixx attributes:

  • data-oo-image-title: defines the (optional) title of an image.
    • The attribute can be applied to <img> elements.
  • data-oo-image-desc: defines the (optional) description of an image.
    • The attribute can be applied to <img> elements.
  • data-oo-image-width: defines the width of the image in the document.
    • The attribute can be applied to <img> elements.
    • A number without a comma is expected.
  • data-oo-image-height: defines the height of the image in the document.
    • The attribute can be applied to <img> elements.
    • A number without a comma is expected.
  • data-oo-image-sizeunit: definiert die Einheit. Standardmässig wird Pixel (px) gewählt.
    • Mögliche Werte: px, cm, mm
    • A number without a comma is expected.
    • More information in the pictures section.

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:

  • If no explicit height ("data-oo-image-height") or width ("data-oo-image-width") specifications are available, the pixel size of the image is used.
  • If a height or width specification is present, the aspect ratio of the original image is kept and the size is calculated accordingly.
  • If both height and width specifications exist, they will be used as size – no matter what aspect ratio the image has.

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:

  • <table>
  • <thead> - within <table>
  • <tbody> - within <table>
  • <tfoot> - within <table>
  • <tr> - within <thead>, <tbody> or <tfoot>
  • <td> - within <tr>
  • <th> - within <tr>
  • All typography elements, images and input controls within a <td>.
  • Lists within a <td>.
  • Tables within a <td>

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

OneOffixx attributes:

  • data-oo-table-width: defines the width of the table in percent or "twip" (1cm = 567). Is optional if data-oo-table-columns values are specified as cm.
    • The attribute can be applied to <table> elements.
  • data-oo-table-width-unit: Pct/Dxa/Nil/Auto. Pct is selected by default. Dxa stands for the twip specification.
    • The attribute can be applied to <table> elements.
  • data-oo-table-layout: Fixed/AutoFit. Fixed is selected by default. With AutoFit, the respective column is enlarged in the case of overlong columns.
    • The attribute can be applied to <table> elements.
  • data-oo-table-columns: defines the width of the respective columns within a table in percent or as cm values.
    • The attribute can be applied to <table> elements.
    • The values are to be specified comma-separated, in each case per column.
  • data-oo-table-look-*: Through this attribute the Word table can be specified more precisely, e. g. whether a result row is visible or not. The properties are the same as the TableLook-Properties from the OpenXML SDK.
  • data-oo-table-look-firstRow: True/False - Headline: Show special formatting for the first line.
  • data-oo-table-look-lastRow: True/False - Results row: Show special formatting for the last line.
  • data-oo-table-look-firstColumn: True/False - First column: Show special formatting for the first column.
  • data-oo-table-look-lastColumn: True/False - Last column: Show special formatting for the last column.
  • data-oo-table-look-noHBand: True/False - Banded lines: Show special formatting for even or odd rows.
  • data-oo-table-look-noVBand: True/False - Banded columns: Show special formatting for even or odd columns.
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:

  • <input type="checkbox" >
    • The "checked" attribute is evaluated.
  • <input type="datetime" >
    • The "value" attribute is evaluated.
  • <input type="text" >
    • The "value" attribute is evaluated.
  • <textarea >
    • The text content is evaluated.

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:

  • <ul> - displayed as a bullet list without style specification.
  • <ol> - without style specification displayed as numeric list
  • <li> - within <ul> or <ol>
  • All typography elements, images and input controls inside a <li>.
  • Nested lists, keeping the 'numbering' style of the main list, within a <li>

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 OneOffixx 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="OneOffixx">
<![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 OneOffixx 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>first column</td>
                <td>second column</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 OneOffixx 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>