ImageFrame XML

XML Structure

Any item within a frames list of type "image", corresponding to a ?Document Object Model - ImageFrame object:

<document>
  <pages>
    <item>
       <frames>
          <item type="image" x="10mm" y="10mm" width="50mm" height="20mm" externalID="123-456-789" path="MY_FOLDER\MY_IMAGE.jpg" ...various other required attributes... />
       </frames>
    </item>
  </pages>
</document>

XML Shortcut

Placing images requires a whole series of attributes to be set properly. To facilitate creating new Image Frames in XML, the placement (and most importantly the internal positioning) of images have a shortcut in the document's XML:

<document>
  <pages>
    <item>
       <frames>
          <item type="image" x="10mm" y="10mm" width="50mm" height="20mm" fitMode="proportional" >
            <assetXML>
               <item ...VALID DEFINITION XML PROPS + CONTENT... />
            </assetXML>
          </item>
       </frames>
    </item>
  </pages>
</document>

A sub-node "assetXML" can be added to an image frame, which contains in its turn an "item" node which represents a valid resource item definition XML.This is the same definition XML to update an image variable value, or to manipulate an image frame using JavaScript. For more information on its structure and use:

This assetXML will be used by CHILI Editor (when opening the document) to populate the image frame with all the correct values.
If an image was already placed in the imageframe (e.g.: as a placeholder image), don't forget to remove the subnodes of the frame that relate to the old asset (like boxes & metadata).
These will be recreated by the editor once the new image is placed inside the image frame.

Required content attributes

If you do update or create an image frame directly through its XML node, the following content is required to be present and correct:

externalID: the original asset's ID on the CHILI Server
realWidthPixels and realHeightPixels (realWidth and realHeight are not needed, these are for display only, and are calculated based on resolution + value)
realResolution
box, boxes, numPages and pageNum (if applicable, eg for PDF). See lower
if "fitMode" = "manual":
- imgX, imgY, imgWidth, imgHeight and imgRotation. These position the image within the image frame.
if fitMode is not "manual", the image position will be calculated by CHILI Editor

The "real" information (widthPixels/heightPixels/resolution) can be found in the asset's definition XML (the "fileInfo" sub-node).

NOTE: for manually positioned images, you should ensure that imgWidth / imgHeight have the same proportions as realWidthPixels / realHeightPixels (this is not enforced when parsing the XML)

Positioning

Positioning of images depends primarily on the fitMode property (of type ?Editor Enumerations - ImageFitMode). For all but "manual" placement, the image positioning (imgX, imgY, imgWidth, imgHeight and imgRotation) is calculated by CHILI Editor (so this is not required to be present in the XML), based on:

The frame's dimensions (width/height)
The frame's inset (insetLeft, insetTop, insetRight and insetBottom) and border type
If applicable, the image frame's fitPoint (for the various proportional placement types)
The actual placed asset's real dimensions (including resolution)
The selected box (for PDF files, see lower)

Within the image's position, the "imageFlip" property may furthermore flip the image content horizontally, vertically or both.

Frame and Image Shapes

An Image Frame can have two types of shapes applied, in the properties:

clippingPath (applied to the placed image)
frameClippingPath (applied to the frame as a whole, irrespective of the asset which may or may not be placed)

See ?ShapeFrame XML and Paths XML for more information on a path's XML structure

PDF box and Page

When placing a PDF file into an ImageFrame's XML, the following content should also be updated based on information from the asset's definition XML:

boxes: a list of type ?Document Object Model - ImageFrameBoxes, containing ?Document Object Model - ImageFrameBox items
box: a reference (by ID) to the selected box (default = "Full" box, see lower)
If relevant, set boxLeft, boxRight, boxTop, boxBottom to "false", to skip one side of the box clipping
numPages and pageNum

Individual Box definitions contain normalized percentages based on the PDFs media width (0-1, where 1 = 100%).