Media and images


Naturally, XP can also store any files you would want to serve or associate with any data. This chapter explores how XP stores uploaded data and focuses on how its image tools work. At the end of the chapter we’ll walk through how to use images in a headless fashion.

The tasks and examples in this chapter are based on work done in previous chapters (starting with the sandboxes chapter). If you want to follow along with the examples, make sure you’re all caught up. This chapter requires that you’ve got your site up and running.

Media types

Media types are content types that ship with XP. When you upload a file to XP, XP will assign it one of a number of preexisting media types based on the file’s content. Some common media types are images, audio, video, and executables.

For a full overview of all the media types baked into XP, see the reference docs for media content types.

Uploading media

To upload files to Content Studio, use the "create content" dialog. You can either click the "upload" icon in the dialog or you can drag and drop the files from your file explorer.

The drag and drop interface. Three file icons being dragged onto a large, blue, circular drop zone.
Figure 1. Dragging and dropping files to the "create content dialog"

This process is the same for whatever media type you want to upload.

Task: Uploading images

To get familiar with uploading media to XP, let’s start with one of the most common media types on the web: images! As mentioned above, this process will also work for any other media type.

  1. Find an image to upload. For the purposes of the tasks in this chapter, you should work with an image where the important part isn’t centered in the shot. If you have one yourself, feel free to use that. If not, how about using this picture of a lion by Keyur Nandaniya?

  2. Create a folder for your images. Call it "images". Just like the "artist" folder we created previously, place the folder directly under your site.

  3. Open the "create content" dialog. Press the upload button to bring up your OS’s file browsing dialog and select your image. You can also drag and drop the image from your file system browser onto the dialog.

And that’s all it takes to upload files to Content Studio!

Media in Data Toolbox

Like we saw in the chapter on content, Data Toolbox lets you view and edit your content. Images and other media are also available in Data Toolbox as content, but in addition to the same properties you saw previously, media also have a property called attachment. The attachment specifies the actual media file that you have uploaded.

For instance, if you have a look at the image you uploaded earlier, you should see that it points to the image file you uploaded. If you added a focal point, you’ll see that specified under the media property too. If you view the content as JSON, some relevant parts of the structure are the data and attachment properties:

An extract of the JSON representation of an image
// ....
  "data": {
    "media": {
      "attachment": "lion.jpg", (1)
      "focalPoint": { (2)
        "x": 0.246875,
        "y": 0.6653906106948853
  "attachment": { (3)
    "name": "lion.jpg",
    "label": "source",
    "binary": "lion.jpg",
    "mimeType": "image/jpeg",
    "size": 256018,
    "text": ""
// ....
1 References the name of the attachment specified in the attachment property.
2 If you have set a focal point, its position will also show up here. See the next task for how to set one.
3 The image attachment with data about the file, such as MIME type and size.

XP’s image service

Whenever XP serves you an image, either via the headless API or in a traditional CMS solution, the image is served via XP’s image service.

The image service takes care of scaling and applying filters to your images based on parameters you give it. For instance, it’s common to want to have all images in a section conform to the same dimensions. But because images are generally of different shapes and sizes, this might require cropping the image. The image service takes care of that for you as long as you specify what you want.

The image service works in tandem with Content Studio’s image editing tools, so it respects crops, flips, and focal points that you create.

Editing images

Content Studio comes with a suite of image editing tools built in. After uploading an image to Content Studio, you can find it in the content grid and edit it to bring up the image’s content form.

A content form showing the image with image editing tools, inputs for caption, alternative text, copyright, and tags.
Figure 2. The image content form

The content form allows you to provide an image caption, alt text, copyright and tag info. You can also add image properties such as dimensions, and where the image was taken and with what gear. Note that changing these properties, including size, width, height, etc, does not affect the image in any way.

The image editing tools allow you to crop, flip, and rotate the image as well as to set what’s known as autofocus. The autofocus control allows you to set an image focal point that XP will always keep in view, regardless of how the image is cropped. Without setting a focal point, XP will focus around the center of the image when cropping.

You can always reset the edits you’ve made to an image by using the 'reset filters' button.

You can read more about how Enonic simplifies your everyday image problems to get more info about how to use images in a traditional CMS model and for a quick overview of the autofocus feature.

Task: Using autofocus

This task is mostly an exercise in tooling. To see the results of your editing, check out the "Headless: images" section below.

Because we chose an image with an off-center subject, the image might get cropped such that the lion disappears from the image. For instance, a small, square crop might turn out like this:

A crop of the lion in the savannah image. The image is square and the only part of the lion that is visible is part of its hind leg.
Figure 3. Cropped image without focal point

To get around this, try the autofocus tool.

  1. Click the autofocus tool.A red circle will show up over the image. This circle indicates where the focal point is.

  2. Move the circle onto the lion (or whatever your focal point is) and press "apply".

    The lion image with a red circle indicating the focal point around its head.
    Figure 4. The focal point editor

Now, when the image gets cropped, XP will take care of keeping the lion in focus, both in traditional CMS solutions and in headless modes:

A crop of the lion in the savannah. In this square image, the lion is in full view square in the center.
Figure 5. The same image with the same crop, but with a focal point


Guillotine makes it easy to fetch the data that you’ve uploaded. Some functionality is shared between all media types, while other queries only work on specific media types. We’ll look at how to fetch general media and then have a closer look at what we can do with images.

General media

To get the resource URL of media you have uploaded, use the mediaUrl property on any media type. For instance, to get the URL of the raw image you uploaded previously, you could use a query like this:

  guillotine {
      key: "${site}/images") {
      ... on media_Image { (1)
        mediaUrl (2)
1 This allows us to query properties that belong to the media:Image type.
2 The mediaUrl property (also available on all other media types) gives you the relative path (from the server) to the media


XP supports a number of image manipulation functions on the fly. When querying for an image via the GraphQL API, you can use the imageUrl function to specify scale and filters for the result you want.

The scale argument is required and allows you to specify how you want to crop the image. Common scaling functions include block, which allows you to specify width and height and width which scales the image proportionally to the specified width. The scaling methods reference docs show off all the available scaling functions with examples of how they affect the image.

As the name implies, the filters argument lets you apply filters to the image. Use filters to apply coloration functions and to rotate and flip images on the fly. To combine filters, separate them with a semicolon. The filters documentation has an exhaustive list of the available filters.

For instance, we could get all the images under the images folder, scaled to 750x600 pixels, in grayscale, and flipped upside down with a query like this:

A GraphQL query that both scales and applies a filter to images in the images folder
  guillotine {
      key: "${site}/images") {
      ... on media_Image {
        imageUrl( (1)
          type: absolute, (2)
          scale: "block(600,700)", (3)
          filter: "grayscale(); border(10, 0x000000)") (4)
1 The imageUrl function lets you specify how you want the images to look.
2 The type argument specifies whether the URL should be absolute or relative to the server.
3 The scale argument specifies the dimensions of the image.
4 The filter argument lets you apply filters.

The above query should return a response that looks a little something like this:

A response with a cropped image with filters
  "data": {
    "guillotine": {
      "getChildren": [
          "displayName": "lion",
          "imageUrl": "http://localhost:8080/site/default/draft/my-first-site/_/image/3443336b-71e3-40a8-9a04-bc59eae934f8:7e7185830ee56f651aee49bf4aa98231ff8c1ecb/block-600-700/lion.jpg?filter=grayscale%28%29%3B+border%2810%2C+0x000000%29"

Which, if you have followed the steps in this chapter, should show you something like this if you try and navigate to the imageUrl property value:

The lion image, cropped, in black and white, and flipped upside down.
Figure 6. The processed image