Structured Text Import

Concept

"Structured text import" allows tagged text to be inserted in a text frame and styled with the use of characters and paragraph styles, but also style overrides like Underline, SubScript, SuperScript and Strikethrough.

The tags and corresponding styles are defined in the document or in the backoffice in a settings file, or can be set using the API.

Tagged text can be inserted in 2 ways

• Through a Structured Text Variable

• Via the API

Styling is applied in the Structured Text Variable setting, or through a settings files.

You can use the variable type: Structured text. This variable accepts "structured text" as input. Structured text is text containing XML tags and/or attributes surrounding the text. These surrounding tags can be used as identifiers to map to Styles (Paragraph - & Character Styles).

Mappings can be defined in 3 ways

• In the document (Structured Text Settings), when you want them specific for 1 document

• In the BackOffice, when you want to reuse the settings in several documents

• Through the API, passing the rules via the API (see below)

The "ImportStructuredText" JavaScript API function to import structured text into a formatted text variable has been removed.

To import text containing XML tags starting with version 6.5, use structured text variables - a new variable type introduced in version 6.3. Structured text variables give you more flexibility and control handling imported tagged text.

Structured text variables can be used server-side in an automated workflow.

Workflow

The source contains tagged (structured) text.

• Check which tags need to be mapped into styles of your CHILI publisher document

• Style definition

  • If your styles have the exact same name, you can opt to map the tags automatically.

  • Or you can define the mapping up-front in the Backoffice.

• Send your structured text into the document

  • Through the API

  • Through Variables (New in 6.3 and 2020.3)

Setting rules in the document

In the panel “Structured Text Settings”, create a new “Structured Text Setting”.

This Setting can contains 1 or more rules or mappings.

Open

The image below shows 1 rule, mapping the Element: “bandcolor” to the fixed ParagraphStyle “brandcolor” (the names don’t need to match, but might be a good practice).

Open

More details: see in the Backoffice Settings, as they follow the same structure.

Backoffice Settings

In the backoffice the setup is done to match the tags in the text file to a style in the document. This can be a character or paragraph style or a styling of the text (underline, ...).
The mapping of a tag can be set to a specific named style or the style can be looked-up automatically in the document based upon the (match) name.

Styles need to be available inside the document and are not created on the fly.

• Match type:

  • Element: You can map an <element> to a style

  • Attribute: You map an <element attribute=”STI”> to a style

• Match name: name of the tag

• Destination:

  • paragraphStyleAutomatic
    will look automatically for a paragraph style in the document with the same name as the element name (as specified in “Match name”) or the attribute value (value of the attribute specified in “Match name”)

  • characterStyleAutomatic
    will look automatically for a character style in the document with the same name as the element name (as specified in “Match name”) or the attribute value (value of the attribute specified in “Match name”)

  • paragraphStyleFixed: use to map a specific paragraph style to the tag specified in the field "Match name". The name of the style is specified in the field "Style name".

  • characterStyleFixed: use to map a specific character style to the tag specified in the field "Match name". The name of the style is specified in the field "Style name".

  • underline: applies an underline on the tagged text

  • subscript: applies the subscript styling to the tagged text

  • superscript: applies the superscript styling to the tagged text

  • strikeThrough: applies a strike-trough on the tagged text

This feature reintroduces functionality available in a previous version - Structured Text Import, that is now only available through the use of the API.

The definition can still be done in the backoffice, or through a structured XML.

The Import Structured Text API allows XML-based content from external sources to be imported seamlessly into a CHILI template using a simple JavaScript command. The imported text can be inserted directly into any text frame or into any formatted text variable. By defining a set of simple rules, the XML structure is mapped to paragraph and character styles used within that template.
Import structured text into a formatted text variable via JavaScript

 or

 Import structured text into a text frame via JavaScript 

 
Template example:

Integration / API

The rules can be defined in the CHILI BackOffice or provided as pre-configured XML.

Here is an example of rules XML:  

The API is available on the following objects

• TextFrame

• Variable of type Formatted Text

JavaScript code to set the Structured Text

CHILI publisher does not support inheritance. By consequence, this also applies to structured / nested tags.

When <brown> is mapped to a style with the color brown, and <lazy> is mapped to a bold style, “lazy” will not be brown. (unless the Lazy style is also defined to be brown)

In Desktop applications, the concept of “Styles based on…” is used, this is not supported in CHILI publisher.