Content Media

New in MP 2.12:

With 2.12, content objects can have more than one media slot. Use the following resources to manage slots and their media:

• GET /{iid}/content/{uuid}/slots
• GET /{iid}/content/{uuid}/slots/{slot_uuid}
• PUT /{iid}/content/{uuid}/slots/{slot_uuid}
• DELETE /{iid}/content/{uuid}/slots/{slot_uuid}
• GET /{iid}/content/{uuid}/slots/{slot_uuid}/media
• POST /{iid}/content/{uuid}/slots/{slot_uuid}/media
• PUT /{iid}/content/{uuid}/slots/{slot_uuid}/media

Content Media explains the new resources.

(also see ChangeLog)

A content object can have multiple media attached to it. The media is placed inside slots which in turn are placed inside the content. The slots define how the media is displayed on the public site.

Each slot has the following attributes:

• relevance:
  • inline
  • aside
• display (only valid if relevance = 'inline'):
  • carousel
  • gallery

Each media has the following attributes:

• type
• title
• content (XML)
• thumbnail

Depending on the type, the media has additional attributes.

There are three main types of media:

• file (an image and/or audio file from MP's file library)
• embed (embed code, e.g. from a video service)
• external (asset from a CDN or one of the providers recognized by MP)

An external asset is split up into the following subtypes:

• youtube
• vimeo
• soundcloud
• audio
• video

External assets of the type youtube, vimeo or soundcloud have the required attribute url while external assets of the type audio or video have the required attribute urls which is a list of information about the different urls for that specific media slot (see external assets).

Depending on the slot that the media is in, the media will be presented to the MP website's visitors in different ways, e.g. as a carousel or as an aside.

Goal

In the last chapter, we created an article:

• Title: My Last Trip to Rome
• UUID: 11111111-1111-1111-1111-111111111111

In this chapter, we want to spruce it up a little with a few pictures, two videos and an audio report of the trip. The images have already been uploaded to the MP instance (see The File Library):

• Images
  • UUID: dddddddd-dddd-dddd-dddd-dddddddddddd
  • UUID: eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee
  • UUID: ffffffff-ffff-ffff-ffff-ffffffffffff

Let's say one video was uploaded to YouTube, one uploaded to a different video service that allows embedding of the video on another website, and the audio report is stored on a CDN.

Adding Slots

Before we can add the media to the article, we need to prepare the content of the article, i.e. we need to specify where the media is supposed to appear and how it is supposed to be displayed. In order to do this, we need to place <slot> tags inside the content.

Let's say the content of this particular article looks like this right now:

<p>In May, it was time to plan for this year's vacation.</p>
<p>I've always wanted to visit Rome, so I decided now would be the right
time for a trip there.</p>
...
<p>The view from my hotel room was amazing.</p>
...
<p>All in all, I had a fantastic time.</p>

The images are supposed to show up at the top of the article, one of the two videos should be shown next to the sentence about the hotel room, and the second video as well as the audio report should be shown at the end of the article.

To do this, we need to add three slots for media inside the article's content:

<slot id="aaaaaaaa-aaaa-aaaa-aaaa-111111111111" />
<p>In May, it was time to plan for this year's vacation.</p>
<p>I've always wanted to visit Rome, so I decided now would be the right
time for a trip there.</p>
...
<slot id="aaaaaaaa-aaaa-aaaa-aaaa-222222222222" />
<p>The view from my hotel room was amazing.</p>
...
<p>All in all, I had a fantastic time.</p>
<slot id="aaaaaaaa-aaaa-aaaa-aaaa-333333333333" />

Each <slot> tag must have an id attribute.

So, let's PATCH the article:

>>> PATCH("/123/content/11111111-1111-1111-1111-111111111111",
...   {'content': """<slot id="aaaaaaaa-aaaa-aaaa-aaaa-111111111111" />
...                  <p>In May, it was time to plan for this year's vacation.</p>
...                  <p>I've always wanted to visit Rome, so I decided now would be the right
...                  time for a trip there.</p>
...
...                  <slot id="aaaaaaaa-aaaa-aaaa-aaaa-222222222222" />
...                  <p>The view from my hotel room was amazing.</p>
...
...                  <p>All in all, I had a fantastic time.</p>
...                  <slot id="aaaaaaaa-aaaa-aaaa-aaaa-333333333333" />"""})
{'url': 'https://api.metropublisher.com/123/content/11111111-1111-1111-1111-111111111111',
 'uuid': '11111111-1111-1111-1111-111111111111'}

Now that the content is prepared for the slots, we can add the settings for the individual slots, i.e. the slot's relevance and display.

The first slot (id: aaaaaaaa-aaaa-aaaa-aaaa-111111111111) is going to contain the three images and is supposed to be displayed as a carousel. To set the settings for this slot, we send a PUT request to /{iid}/content/{uuid}/slots/{slot_uuid}:

>>> PUT("/123/content/11111111-1111-1111-1111-111111111111/slots/aaaaaaaa-aaaa-aaaa-aaaa-111111111111",
...    {'relevance': 'inline',
...     'display': 'carousel'})
{'content_uuid': '11111111-1111-1111-1111-111111111111',
 'slot_uuid': 'aaaaaaaa-aaaa-aaaa-aaaa-111111111111',
 'url': 'https://api.metropublisher.com/123/content/11111111-1111-1111-1111-111111111111/slots/aaaaaaaa-aaaa-aaaa-aaaa-111111111111'}

The second slot (id: aaaaaaaa-aaaa-aaaa-aaaa-222222222222) will contain the YouTube video and should be shown as a smaller, aside video next to the content:

>>> PUT("/123/content/11111111-1111-1111-1111-111111111111/slots/aaaaaaaa-aaaa-aaaa-aaaa-222222222222",
...    {'relevance': 'aside'})
{'content_uuid': '11111111-1111-1111-1111-111111111111',
 'slot_uuid': 'aaaaaaaa-aaaa-aaaa-aaaa-222222222222',
 'url': 'https://api.metropublisher.com/123/content/11111111-1111-1111-1111-111111111111/slots/aaaaaaaa-aaaa-aaaa-aaaa-222222222222'}

The last slot (id: aaaaaaaa-aaaa-aaaa-aaaa-333333333333) will contain the second video as well as the audio report and should be displayed in a kind of gallery view. The gallery view contains thumbnails for each media. When clicked, the media is shown in an expanded view. The settings for this slot are:

>>> PUT("/123/content/11111111-1111-1111-1111-111111111111/slots/aaaaaaaa-aaaa-aaaa-aaaa-333333333333",
...    {'relevance': 'inline',
...     'display': 'gallery'})
{'content_uuid': '11111111-1111-1111-1111-111111111111',
 'slot_uuid': 'aaaaaaaa-aaaa-aaaa-aaaa-333333333333',
 'url': 'https://api.metropublisher.com/123/content/11111111-1111-1111-1111-111111111111/slots/aaaaaaaa-aaaa-aaaa-aaaa-333333333333'}

Now that the three slots have been placed inside the content and their settings have been defined, we can add media to the slots.

Adding Media

As mentioned in the introduction to this chapter, all media can have a title, (xml-compliant [1]) content and a thumbnail. The respective parameters (title, content, thumb_uuid) are optional. If no thumbnail is specified for a media object, either a default thumbnail is used or, in the case of an image from the file library, the image is resized and used as thumbnail.

The API resource POST /{iid}/content/{uuid}/slots/{slot_uuid}/media is used to add one media item to the possibly existing list of media of a slot. See Setting a Slot's Media for a way to replace the entire list of media in one call.

Image/Audio from File Library

The first media items we want to attach to the article (UUID: 11111111-1111-1111-1111-111111111111) are the three images that already exist in the MP instance's file library. All of them should go in the first slot (id: aaaaaaaa-aaaa-aaaa-aaaa-111111111111):

>>> PUT("/123/content/11111111-1111-1111-1111-111111111111/slots/aaaaaaaa-aaaa-aaaa-aaaa-111111111111/media",
...    {"items": [{"type": "file",
...                "title": "Rome at Night",
...                "image_uuid": "dddddddd-dddd-dddd-dddd-dddddddddddd"},
...               {"type": "file",
...                "title": "Rome by Day",
...                "image_uuid": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee"},
...               {"type": "file",
...                "title": "Shopping Street",
...                "image_uuid": "ffffffff-ffff-ffff-ffff-ffffffffffff"}]})
{'msg': 'media updated'}

The parameter type declares these media to be from MP's file library, which means these are internal links between objects inside the MP instance's database: an article and three images. Therefore, we need to specify the UUID of the images using the parameter image_uuid. This parameter is required for media slots of the type 'file'.

Internal media can also have an audio file from the file library attached to it. In that case send the audio file's UUID as a file_uuid parameter:

{"type": "file",
 "title": "Rome at Night",
 "file_uuid": "cccccccc-cccc-cccc-cccc-cccccccccccc",
 "image_uuid": "dddddddd-dddd-dddd-dddd-dddddddddddd"}

You can send either file_uuid or image_uuid or both to create an internal media.

Embed

The second video we want to attach is a video that was uploaded to a video streaming service similar to YouTube and Vimeo. YouTube and Vimeo are services recongnized by MP and can be added as external asset (see External Assets).

This media though, we'll add as an embed and put it in the third slot:

>>> PUT("/123/content/11111111-1111-1111-1111-111111111111/slots/aaaaaaaa-aaaa-aaaa-aaaa-333333333333/media",
...    {"items": [{"type": "embed",
...                "embed_code": '<iframe width="420" height="315" src="//www.videoservice.com/path/to/file" frameborder="0" allowfullscreen></iframe>'}]})
{'msg': 'media updated'}

External Assets

External assets are created using the parameter type='external' and a specfic subtype (url_type). If the parameter type of a media slot is set to 'external', the parameter url_type becomes required. The additional parameter url or urls is required depending on the value set in url_type.

YouTube, Vimeo, SoundCloud

MP recognizes the video/audio streaming providers YouTube, Vimeo and SoundCloud which means we can easily add such media slots by sending, for example, the YouTube url to the POST /{iid}/content/{uuid}/slots/{slot_uuid}/media resource:

>>> PUT("/123/content/11111111-1111-1111-1111-111111111111/slots/aaaaaaaa-aaaa-aaaa-aaaa-222222222222/media",
...    {"items": [{"type": "external",
...                "url_type": "youtube",
...                "url": "http://youtu.be/OSGv2VnC0go"}]})
{'msg': 'media updated'}

Similarly, Vimeo and SoundCloud media can be added by sending additional information in the items list:

{"type": "external",
 "url_type": "vimeo",
 "url": "http://vimeo.com/40375317"}

{"type": "external",
 "url_type": "soundcloud",
 "url": "https://soundcloud.com/david-greilsammer/mozart-piano-concerto-no-9"}

CDN Audio, CDN Video

The next media we'll add to the article is an audio file. Actually, it is a list of URLs to audio files in different codecs. MP uses the HTML 5 audio (and video) tags to play audio (and video) files. For a more detailed explanation of HTML 5 audio (and video) and the complications, please read Dive Into HTML 5 - Video on the Web.

Suffice to say, when adding CDN audio and video media, you usually need to provide a list of URLs to a file in different codecs in order for the media to play in various browsers.

The following request sent to the POST /{iid}/content/{uuid}/media resource adds a CDN Audio media providing URLs for two differently encoded audio files:

>>> POST("/123/content/11111111-1111-1111-1111-111111111111/slots/aaaaaaaa-aaaa-aaaa-aaaa-333333333333/media",
...    {"type": "external",
...     "title": "Media 4",
...     "image_uuid": "ffffffff-ffff-ffff-ffff-ffffffffffff",
...     "url_type": "audio",
...     "urls": [{"url": "http://www.cdndomain.com/files/rometrip.mp3"},
...              {"url": "http://www.cdndomain.com/files/rometrip.ogg",
...               "mimetype": "audio/vorbis"}]
...    })
{'msg': 'media added'}

The two items in the list of urls are slightly different: one has a mimetype, the other doesn't. Though sending the mimetype for each URL is not required, it is advised to always sent the mimetype for each URL.

Retrieving a Content Object's Media

Our article (UUID: 11111111-1111-1111-1111-111111111111) now has several slots with media. Sending a GET request to /{iid}/content/{uuid}/slots returns a list of the slots and their settings:

>>> GET("/123/content/11111111-1111-1111-1111-111111111111/slots")
{'items': [{'display': 'carousel',
            'relevance': 'inline',
            'url': 'https://api.metropublisher.com/123/content/11111111-1111-1111-1111-111111111111/slots/aaaaaaaa-aaaa-aaaa-aaaa-111111111111',
            'uuid': 'aaaaaaaa-aaaa-aaaa-aaaa-111111111111'},
           {'relevance': 'aside',
            'url': 'https://api.metropublisher.com/123/content/11111111-1111-1111-1111-111111111111/slots/aaaaaaaa-aaaa-aaaa-aaaa-222222222222',
            'uuid': 'aaaaaaaa-aaaa-aaaa-aaaa-222222222222'},
           {'display': 'gallery',
            'relevance': 'inline',
            'url': 'https://api.metropublisher.com/123/content/11111111-1111-1111-1111-111111111111/slots/aaaaaaaa-aaaa-aaaa-aaaa-333333333333',
            'uuid': 'aaaaaaaa-aaaa-aaaa-aaaa-333333333333'}]}

With this list we can find out what media exists in these slots by sending GET requests to /{iid}/content/{uuid}/slots/{slot_uuid}/media:

First slot:

>>> GET("/123/content/11111111-1111-1111-1111-111111111111/slots/aaaaaaaa-aaaa-aaaa-aaaa-111111111111/media")
{'items': [{'content': None,
            'image_mimetype': 'image/jpeg',
            'image_url': 'https://api.metropublisher.com/123/files/dddddddd-dddd-dddd-dddd-dddddddddddd',
            'image_uuid': 'dddddddd-dddd-dddd-dddd-dddddddddddd',
            'slot_uuid': 'aaaaaaaa-aaaa-aaaa-aaaa-111111111111',
            'thumb_mimetype': None,
            'thumb_url': None,
            'thumb_uuid': None,
            'title': 'Rome at Night',
            'type': 'file'},
           {'content': None,
            'image_mimetype': 'image/jpeg',
            'image_url': 'https://api.metropublisher.com/123/files/eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee',
            'image_uuid': 'eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee',
            'slot_uuid': 'aaaaaaaa-aaaa-aaaa-aaaa-111111111111',
            'thumb_mimetype': None,
            'thumb_url': None,
            'thumb_uuid': None,
            'title': 'Rome by Day',
            'type': 'file'},
           {'content': None,
            'image_mimetype': 'image/jpeg',
            'image_url': 'https://api.metropublisher.com/123/files/ffffffff-ffff-ffff-ffff-ffffffffffff',
            'image_uuid': 'ffffffff-ffff-ffff-ffff-ffffffffffff',
            'slot_uuid': 'aaaaaaaa-aaaa-aaaa-aaaa-111111111111',
            'thumb_mimetype': None,
            'thumb_url': None,
            'thumb_uuid': None,
            'title': 'Shopping Street',
            'type': 'file'}]}

Second slot:

>>> GET("/123/content/11111111-1111-1111-1111-111111111111/slots/aaaaaaaa-aaaa-aaaa-aaaa-222222222222/media")
{'items': [{'content': None,
            'slot_uuid': 'aaaaaaaa-aaaa-aaaa-aaaa-222222222222',
            'thumb_mimetype': None,
            'thumb_url': None,
            'thumb_uuid': None,
            'title': None,
            'type': 'external',
            'url': 'http://youtu.be/OSGv2VnC0go',
            'url_type': 'youtube'}]}

Third slot:

>>> GET("/123/content/11111111-1111-1111-1111-111111111111/slots/aaaaaaaa-aaaa-aaaa-aaaa-333333333333/media")
{'items': [{'content': None,
            'embed_code': '<iframe width="420" height="315" src="//www.videoservice.com/path/to/file" frameborder="0" allowfullscreen></iframe>',
            'slot_uuid': 'aaaaaaaa-aaaa-aaaa-aaaa-333333333333',
            'thumb_mimetype': None,
            'thumb_url': None,
            'thumb_uuid': None,
            'title': None,
            'type': 'embed'},
           {'content': None,
            'image_mimetype': 'image/jpeg',
            'image_url': 'https://api.metropublisher.com/123/files/ffffffff-ffff-ffff-ffff-ffffffffffff',
            'image_uuid': 'ffffffff-ffff-ffff-ffff-ffffffffffff',
            'slot_uuid': 'aaaaaaaa-aaaa-aaaa-aaaa-333333333333',
            'thumb_mimetype': None,
            'thumb_url': None,
            'thumb_uuid': None,
            'title': 'Media 4',
            'type': 'external',
            'url_type': 'audio',
            'urls': [{'mimetype': None,
                      'url': 'http://www.cdndomain.com/files/rometrip.mp3'},
                     {'mimetype': 'audio/vorbis',
                      'url': 'http://www.cdndomain.com/files/rometrip.ogg'}]}]}

Depending on the media's type (and where available url_type), the individual items in the list returned here contain different information. For example, the items in the list returned for the slot aaaaaaaa-aaaa-aaaa-aaaa-11111111111 are files from MP's file library (type = 'file') and have image_* information while the first item in the list returned for the slot aaaaaaaa-aaaa-aaaa-aaaa-333333333333 is an embed media (type = 'embed') and has embed_code information but no image_* information while the second item is an external audio file and has image_* informatation as well as urls.

Setting a Slot's Media

Attention

Using this resource overwrites the existing media of the slot.

In the section adding media, we created individual media and appended them to the various slots inside the content object. There's an easier way to set the entire list of media for one particular slot using the PUT /{iid}/content/{uuid}/slots/{slot_uuid}/media resource:

>>> PUT("/123/content/11111111-1111-1111-1111-111111111111/slots/aaaaaaaa-aaaa-aaaa-aaaa-111111111111/media",
...     {'items': [{"type": "file",
...                 "title": "Beautiful View of Rome at Night",
...                 "image_uuid": "ffffffff-ffff-ffff-ffff-ffffffffffff"},
...                {"type": "external",
...                 "url_type": "youtube",
...                 "url": "http://youtu.be/OSGv2VnC0go"}]})
{'msg': 'media updated'}

This resource takes the parameter items. Each item of the list defines one media.

Footnotes

[1]	The content field of media slots allows XML-compliant HTML, with restrictions. The field value must comply with the HTML schema shown in RelaxNG Schema for XML-compliant HTML.