Media Field Configuration

This plugin is able to display any of the media types that are supported by TimelineJS. That said, configuring your entity fields so that all of these media types can be added while simultaneously ensuring a good user experience for your content creators can be a real challenge! Listed below are some tips for setting up your entities and view. If you come up with a different combination of fields, settings, or other contributed modules that works well for you, please share it with the community by posting an issue in our queue!

For the purposes of thinking about how to implement media fields they can be divided into at least four categories:

• Images - If you're planning on linking exclusively to external images, then you can simply treat the Image as you would any other Embeddable media (see below). Otherwise, you will need some means to upload the images into your Drupal site.
• Embeddable media - Most of the media types supported by TimelineJS fall into this category. Provide TimelineJS with a URL to a media resource that it recognizes and it will use that resource's API to embed it for you.
• Blockquote - TimelineJS can display text as media, provided that you wrap the text in HTML blockquote tags, <blockquote>...</blockquote>.
• iframe - TimelineJS recommends using <iframe> elements to embed media for which it doesn't have native support. You can use the same text field as you use for blockquotes, but it is listed here separately because there may be security issues associated with allowing content to be embedded from untrusted sources. Consult web security experts for more information. Limit the ability to add iframes by giving only trusted user roles permission to use text formats that allow iframes in HTML!

Here are some configuration recipes for implementing media.

A text field using CKEditor

CKEditor is an all-in-one solution for implementing all possible types of media with a single field. You can paste URLs, enter HTML, and even upload images directly into the field. Unfortunately, there are drawbacks.

Pros:

• One field may be better UX for content creators than multiple specialized fields.
• Fewer fields to configure in Views.

Cons:

• CKEditor loves to do things like wrap nearly everything with HTML tags. After all, it is a WYSIWYG editor. This can lead to unexpected behavior when entering your data. You can get around it by switching the editor into "Source" mode, but that isn't an ideal solution. If the content is edited later, the field won't be in Source mode. The editor will re-wrap text with HTML and escape HTML entities. The media may be broken without anyone realizing it!
• URLs pasted directly into the editor may or may not work. In testing, a URL to a Google map was successfully embedded, but a URL to a YouTube video was not.
• You can't apply styles to images uploaded via the editor.
• URLs are not validated.

Separate Link, Image, and Text fields

Using multiple fields is possible if you properly configure your view. You have to set up your fields so that if one field is empty, it will fall back to the output of another field, in successive order. You do this by editing the No Results Behavior of a field in Views.

For example, if you know that you will only need to embed supported media and images, follow these steps:

1. Add a Link field and Image field to your slide entity.
2. When you create your view, add those fields. Place the Link field above the Image field in the field list. The order is important!
3. Change the No Results Behavior of the image field, pasting the Replacement Pattern for the link field, e.g. {{ field_timeline_media_url }}, into the No Results Text.
4. In the Format settings, change the Media field mapping to map to your Image field.

With this configuration if the image field is empty, it will fall back to outputting the URL that is given by the link field.

Why was the order of the fields important? The reason is that Views will escape HTML entities in fields that are used as replacement patterns. If any replacement field outputs HTML, then TimelineJS will not be able to render the media. Getting around this problem is the tricky part of setting up the view. You can only have one media field that outputs HTML; other fields used as replacement values must output a raw URL. That one HTML field must be placed below the other media fields in the list. The last field is the one that gets mapped in the Format settings.

Here is another example with a Link, Image, and Text field in order to support all possible media, including <blockquote>. Because there are two fields that will output HTML you will have to do some extra configuration.

1. Download an enable the Image URL Formatter module. It will allow you to output your Image field as a raw URL.
2. Add a Link field, an Image field, and a Text field to your slide entity.
3. Add your new fields to the view. The Link and Image field can go in any order, but the Text field must be placed below them in the list because it is the one field that will output HTML.
4. Edit the Image field's settings. Change the Formatter to Image URL.
5. Assuming the Link field is first in the field list, paste its replacement pattern, e.g. {{ field_timeline_media_url }}, into the Image field's No Results Text.
6. Paste the Image field's replacement pattern, e.g. {{ field_timeline_media_image }} into the Text field's No Results Text.
7. In the Format settings, change the Media field mapping to map to your Text field.

Pros:

• Discrete data fields for images and links, including whatever benefits they may provide, such as image styles and URL validation.
• Little to no need for dealing with annoying text editor settings every time you enter or edit data. The bulk of the work is done only once in the back end through Views configuration.

Cons:

• Multiple fields may be confusing for content creators, resulting in bad UX. Field Help Text should clearly indicate which fields override others. In the first example, the Image field overrides the Link field. If both fields have data then the image will be displayed and any URL in the Link field will be ignored.
• Getting the field configuration working in Views may be a challenge for some site builders.