General XML Concepts

Documentation of XML structure

For most objects, an overview of available properties is described in Document Object Model.

XML Validation and calculations

When updating (or generating) XML for a document, you should keep in mind that little validation (or automatic triggering of other content) is in place, whereas this IS available through the editor (and in almost all cases also when updating content through JavaScript). For example, updating variable values does not necessarily push the content of those variables into the text frames where they are used, EXCEPT when the document is opened in the Editor itself. Similarly, positioning of texts (for PDF generation) is calculated by the Editor.

To force this type of update, you can set the document's root node's "savedInEditor" property to "false" (for existing documents), or omit it completely (for new documents). Whenever the XML is used on the CHILI server for preview or PDF generation, this will tell CHILI to (in the background) perform those calculations by opening it inside the editor and applying the rules / performing the calculations.

This also means that in general it is MUCH easier to take existing XML content, and updating that (or duplicating it), rather than generating everything from scratch.

General Data Types

Within the Document Object Model documentation, you will find the data type of all properties of the various objects. These include:

string
number
int
bool
unit
TextFlow
ITextLayoutFormat
Enumerations
Complex CHILI Objects

string: seems self-evident

number: a decimal number, without thousands-separator, and technically supporting both "," and "." as decimal separator (although internally CHILI will always use the period, so that is definitely the safest way to go)

int: an integer

bool: a boolean. Best practice is to use "true" and "false" (lowercase) as values, although in most locations "True" and "False" will also be accepted

unit: see lower

TextFlow and ITextLayoutFormat: see lower

Enumerations: inserted as a string value containing a valid value for the enumeration type (see lower for more info)

Complex CHILI Objects: see lower

Of these data types, most will be serialized/deserialized in the document's XML structure as attributes of the item's node. Exceptions to this rule are :

TextFlow (which is inserted in a sub-node, which in turn contains the complete textflow XML)
ITextLayoutFormat (which is inserted in a sub-node, containing attributes describing the format)
Complex CHILI Objects, if not referenced (see lower)

Complex CHILI Objects

CHILI objects are serialized in a number of ways:

document itself (root node)
as a list item
as a property of another CHILI Object, referencing a list item
as a property of another CHILI Object (but not referenced)

Any CHILI document's XML starts with the description of Document object model - Document (see ?Document XML structure overview for a basic overview of a CHILI document's main structure)

The document itself has a series of properties, such as width/height (of type "unit"), and layers (of type Layers). Using that information, a basic XML could look like:

<document width="100mm" height="100mm">
   <layers>
     <item name="Layer1" visible="true" />
     <item name="Layer2" visible="false" />
   </layers>
   <preflightPreferences textOverflow="error" />
</document>

Obviously this XML does not contain all information inside a CHILI Document. All other content will be appended based on the default settings by CHILI Editor, though (1 page, the default colors, etc.). But it demonstrates the basic data types:

The document object contains a series of "simple" data types (width / height ), which are inserted as attributes of the main node.

It also contains a series of properties which are complex CHILI Objects (described further lower). Unfortunately, we are usually very consistent in naming conventions. Overall, that's a good thing, but for this documentation it will get a little bit confusing (a property "layers" of type "Layers", a property "preflightPreferences" of type "PreflightPreferences", with only the case of the first letter different).

So the document object contains a "layer" property, of type "Layers", which is in turn a Complex CHILI Object (?Document Object Model - Layers). As it is not a referenced oject, this is serialized in a sub-node of the "document" node, using the name of the property ("layers"). The "Layers" object has no properties of its own, but inherits from DocumentBaseList, so it can contain list items. Items are always serialized as a series of "item" nodes under the parent's node (so: "document > layers > item").

Each "item" node under the "layers" node in turn represents a Complex CHILI Object, of type ?Document Object Model - Layer. As a list item, it inherits certain properties (name, id, ...) from DocumentListItemBase. In the previous sample, "id" is not populated (see lower for more info), and "name" is. the "Layer" object itself has a "visible" property (of type "bool"), which is included in the XML.

The basic (top-level) "Document" object also contains a property "preflightPreferences", of datatype ??Document Object Model - PreflightPreferences. This is not a list, and corresponds to the settings for preflighting the current document. Being again a complex CHILI Object, it is serialized as a sub-node of the parent ("document"), with its properties again following the same rules. This object contains a series of properties, many of which, including the "textOverflow" property, are an enumaration type (?Editor Enumerations - PreflightResultType). One of the allowed values for this enumeration is "error", which is included as an attribute on the main object node.

A (slightly) more complex CHILI document's XML might look like:

<document width="100mm" height="100mm">
   <pages>
      <item>
         <frames>
            <item type="rectangle" x="10mm" y="10mm" width="80mm" height="80mm" layer="1234-4567-90123-456" />
         </frames>
         <sectionOptions newSection="true" pageStart="4" />
      <item>
   </pages>
   <layers>
     <item name="Layer1" id="1234-4567-90123-456" visible="true" />
     <item name="Layer2" id="9876-5432-109877-654" visible="false" />
   </layers>
</document>

This document XML also contains the definition of a single page and frame. To get to thepoint of a single frame, we serialized:

The document
The document's "pages" property, of type ?Document Object Model - Pages, which is a list, and therefore can contain "item" nodes to represent the list's items
- A single page "item" node, of type ?Document Object Model - Page (in which most properties are ignored in this XML sample), with properties:
  - sectionOptions, of type ?Document Object Model - SectionOptions, only having the "newSection" and "pageStart" properties in the XML. sectionOptions is a complex CHILI Object, not a list item, and not referenced, so it gets a sub-node with the name of the property ("sectionOptions"), containing the object's properties in return
  - frames, of type ?Document Object Model - Frames
    - a single frame "item" node in the list, of type ?Document Object Model - RectangleFrame (see lower for an explanation of the various Frame Types), containing only a couple of inserted properties:
      - type = "rectangle" (see lower)
      - x / y / width / height: properties of type "unit", describing the position of the frame
      - a "layer" property, which refers to a list item. This is a Complex CHILI Object by reference, meaning that the referred object's ID is inserted into the XML

NOTE: for display purposes, CHILI Editor will serialize a document's XML not only containing a referenced object's ID, but also its name. When updating/creating XML, this is not required. Eg:

<frames>
   <item layer="1234-4567-90123-456" layerName="Layer1" />
</frames>

the structure of this is always xxxName, were "xxx" is the original property (in the sample's case: "layer")

Object Inheritance

Complex CHILI Objects may inherit properties and functions. All objects, for example, inherit from ?Document Object Model - DocumentBase. That means that any object in the XML structure can contain a set of common properties, such as:

tag (editable for frames, in the "Frame Location" Panel)
alternateLayoutProperties (used to store property values of alternate layouts: ?Alternate Layouts XML

Other types of objects may inherit from multiple levels (see lists and frames lower).

Lists and list items

Lists in XML can be identified in the Document Object Model as complex objects which inherit from ?Document Object Model - DocumentListBase (and similarly for list items: DocumentListItemBase).

When serializing/deserializing lists, all content of the list (the individual items) will be serialized as "item" nodes under the main object's node.

List items all inherit from ?Document Object Model - DocumentListItemBase, which mean they can have an ID. While an item ID can be any string, we strongly recommend using a Globally Unique Identifier (GUID). Your development environment undoubtedly contains a function to generate this (for C#, for example, you can use:

string myNewID = Guid.NewGuid().ToString();

Also note that an ID is not an absolute requirement when constructing or updating list items. When creating new XML and omitting ID attributes, CHILI Editor will automatically assign them (and keep them) upon first serializing the XML.

In addition, note that an exception to the ID and naming convention of list items exists for fonts: ?Fonts XML

Measurement units

see ?Measurement Units for more details on the format (and some conversion sample code) of measurement units.

TextFlow and ITextLayoutFormat

See ?TextFlow and ITextLayoutFormat XML

Enumerations

Within the Document Object Model, many properties are enumerations. A list of the available enumerations (and more importantly: the allowed values) can be found in ?Editor Enumerations.

The string value for an enumeration item can be retrieved from this documentation as follows:

If it is "empty" (empty = true in the documentation), you can pass an empty string
If it has a "value", you can pass that
Otherwise you can use its "name"

Frames

Pretty much all lists in the Document Object Model contain list items of a single type ("Layers" - "Layer", "Pages" - "Page", etc.). Frames are a special case, though. The list of a Frames object can contain objects of various types, although all inherit from ?Document Object Model - Frame. Individual frames types are described in the ?Editor Enumerations - FrameType enumeration, and those are inserted into the XML as the "type" property of a frame's item node. When parsing the XML, this type is used to then find the correct frame object (ImageFrame, TextFrame, etc.). Let's take the following bit of XML as a (non-exhaustive) sample:

<frames>
   <item type="rectangle" x="10mm" y="10mm" width="50mm" height="50mm" />
   <item type="image" x="10mm" y="70mm" width="50mm" height="50mm" externalID="123-456-789" />
   <item type="text" x="10mm" y="130mm" width="50mm" height="50mm" >
      <textFlow>
         VALID TEXTFLOW XML HERE
      </textFlow>
   </item>
</frames>

NOTE: this is NOT valid XML, it is for demonstration purposes only

In here, all frame item nodes contain some shared properties (type, x/y/width/height), because all frames are of type ?Document Object Model - Frame. Depending on the "type" property, the individual frames then become typed to:

where the "externalID" and "textFlow" properties are only available for an Image and Text Frame respectively.