Resolving content items and components in Rich text

Juraj Uhlar edited this page Oct 22, 2018 · 2 revisions

Contents

  1. Introduction
  2. Linked items in Rich text
  3. Implementing a resolver
  4. Retrieving Rich text content

Introduction

This page describes how to resolve content items and components inside Rich text elements.

Items and components in Rich text

Rich text elements in Kentico Cloud can contain other content items and components. For example, if you write a blog post, you might want to insert a video or testimonial to a specific place in your article.

Note: Items and components are resolved using the same mechanism; your application does not need to differentiate them. You can learn more about the differences between items and components in our API Reference.

Without adjusting your application, any content item or component in a Rich text element will resolve to an empty object reference, which won't be rendered on the page.

<object type="application/kenticocloud" data-type="item" data-codename="donate_with_us"></object>

To display the content in the rich text on your website, you need to define exactly how it should be rendered:

  1. Implement a content resolver
  2. Register the resolver within the DeliveryClient instance
  3. Retrieve content of a Rich text element

For example, let's say you want to add YouTube videos to your article. In such a case, you would need a content type YouTube video with a single Text element for the Video ID.

Implementing a resolver

Your resolver must implement the InlineLinkedItemsResolverInterface interface, which defines the resolveInlineLinkedItems() method for resolving items and components to HTML markup.

Note: We recommend to return a valid HTML5 fragment.

class CustomLinkedItemsResolver implements InlineLinkedItemsResolverInterface
{
    public function resolveInlineLinkedItems($input, $item)
    {
        if(empty($item)){
            return $input; 
        }

        switch ($item->system->type) {
            case 'youtube_video':
                return "<div><iframe type=\"text/html\" width=\"640\" height=\"385\" style=\"display:block; margin: auto; margin-top:30px ; margin-bottom: 30px\" src=\"https://www.youtube.com/embed/".$item->elements->video_id->value."?autoplay=1\" frameborder=\"0\"></iframe></div>";
        }

        return $input;
    }
}

If the resolver or the content item itself is not available, the object reference remains in html.

When are content items available?

  • For the live environment, a content item is available when published, and unavailable when deleted or unpublished.
  • For preview environment, a content item is available when it exists in the project inventory, and unavailable when deleted.

Components are an integral part of their content items and are always present in the response.

Registering a resolver

Once you implement the resolver, you need to register it in the DeliveryClient.

// Sets the resolver as an optional dependency of the DeliveryClient
$client = new DeliveryClient("975bf280-fd91-488c-994c-2f04416e5ee3");
$client->inlineLinkedItemsResolver= new CustomLinkedItemsResolver();  

Custom default resolver

If you need to customize the application behavior for cases when no resolution for type exists, you need to extend the resolveInlineLinkedItems method by the default statement.

// Sample resolver implementation
class CustomLinkedItemsResolver implements InlineLinkedItemsResolverInterface
{
    public function resolveInlineLinkedItems($input, $item)
    {
        if(empty($item)){
            return $input; 
        }

        switch ($item->system->type) {
            case 'youtube_video':
                return "<div><iframe type=\"text/html\" width=\"640\" height=\"385\" style=\"display:block; margin: auto; margin-top:30px ; margin-bottom: 30px\" src=\"https://www.youtube.com/embed/".$item->elements->video_id->value."?autoplay=1\" frameborder=\"0\"></iframe></div>";
            default:
                return "<div>Content not available.</div>";
        }
    }
}

Retrieving Rich text content

Now, when you retrieve the content of a Rich text element via a property, items and components based on the Youtube video will be resolved correctly.

// Retrieves the 'Coffee beverages explained' article
 $item = $client->getItem('coffee_beverages_explained');

// Retrieves text from the 'body_copy' Rich text element
$description = $item->bodyCopy;

The HTML output of your content item resolver is now included in the Rich text.

<div><iframe type=\"text/html\" width=\"640\" height=\"385\" style=\"display:block; margin: auto; margin-top:30px ; margin-bottom: 30px\" src=\"https://www.youtube.com/embed/wZZ7oFKsKzY?autoplay=1\" frameborder=\"0\"></iframe></div>

Analytics

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.