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 thecontent-type
resource: you can, however omit some of the representations. If you omit an object for one of therepresentation
s, then a default soft crop is created that has the aspect ratio defined in thecontent-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 acrop
object. -
Each
crop
object must contain the following values:x
andy
-
These coordinates define the crop start point in pixels, and are measured from the top-left corner of the image.
height
andwidth
-
These co-ordinates define the height and width (in pixels) of the area to be selected.
If the
representation
definition in thecontent-type
resource includes both an output height and width as in the examples above then theheight
andwidth
values specified in the crop object should normally have a matching aspect ratio, as is the case in thethumbnail
andnarrow
crop objects shown above. If you specifyheight
andwidth
values that do not match therepresentation
's aspect ratio, as is the case in thewide
crop object shown above, then the Content Store will crop the specified area but stretch or compress it to fit therepresentation
'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/.