Importing Soft Crop Definitions

Image content items can contain soft-crop definitions: image cropping co-ordinates that allow the Content Store to generate a variety of cropped versions of an image on the fly, rather than having to store multiple versions of every image. In order for a publication to support soft-cropping of images, its image content types (as defined in the content-type resource) must include a field for storing this information. Here is an example of a content type definition that includes such a field, called representations in this case:

<content-type name="image">
...
  <panel name="crop">
    <ui:label>Cropped Versions</ui:label>
    <field mime-type="application/json" type="basic" name="representations">
      <ui:label>Image Versions</ui:label>
      <rep:representations type="image-versions">
        <rep:representation name="thumbnail">
          <rep:output width="100" height="100"/>
          <rep:crop/>
          <rep:resize/>
        </rep:representation>
        <rep:representation name="narrow">
          <rep:output width="500" height="400"/>
          <rep:crop/>
          <rep:resize/>
        </rep:representation>
        <rep:representation name="wide">
          <rep:output width="1000" height="800"/>
          <rep:crop/>
          <rep:resize/>
        </rep:representation>
      </rep:representations>
    </field>
  </panel>
...
</content-type>

Note that the field's mime-type is set to application/json. This means that the field is configured to store JSON-formatted data (JSON is a popular data exchange format in web applications). For more information about this, see Importing Soft Crop Definitions.

This means that in order to import soft crop information with an image, you must include the appropriate field (as defined in your content-type resource) and insert the soft crop definitions, in JSON format in this field. For example:

<content source="ex" sourceid="20" type="picture" state="published">
  <section-ref source="ex" sourceid="s2" home-section="true"/>
  <field name="title">Croc</field>
  <field name="caption">A Croc on the beach</field>
  <field name="binary" title="crocodile">/tmp/escenic/import/croc.jpg</field>
  <field name="representations">
      {
        "thumbnail":
          {
            "crop":
              {
                "width":400,
                "height":400,
                "x":0,
                "y":54
              }
          },
        "narrow":
          {
            "crop":
              {
                "width":250,
                "height":200,
                "x":0,
                "y":54
              }
          },
        "wide":
          {
            "crop":
              {
                "width":400,
                "height":400,
                "x":102,
                "y":100
              }
          }
      }
  </field>
</content>

The important points to be aware of here are the following:

  • The JSON structure may contain one object for each representation defined for the field in the content-type resource: you can, however omit some of the representations. If you omit an object for one of the representations, then a default soft crop is created that has the aspect ratio defined in the content-type resource, is as large as possible and is positioned in the center of the image.

  • A representation object's crop data must be encapsulated in a crop object.

  • Each crop object must contain the following values:

    x and y

    These coordinates define the crop start point in pixels, and are measured from the top-left corner of the image.

    height and width

    These co-ordinates define the height and width (in pixels) of the area to be selected.

    If the representation definition in the content-type resource includes both an output height and width as in the examples above then the height and width values specified in the crop object should normally have a matching aspect ratio, as is the case in the thumbnail and narrow crop objects shown above. If you specify height and width values that do not match the representation's aspect ratio, as is the case in the wide crop object shown above, then the Content Store will crop the specified area but stretch or compress it to fit the representation's aspect ratio, resulting in a distorted image.

  • White space is irrelevant in the JSON format: you can compress all of the representations field in the above example into a single line if you wish.

  • Order is also irrelevant in JSON.

For detailed information about the JSON format, see http://www.json.org/.