Delivering Content Fragments delivering-content-fragments
Adobe Experience Manager (AEM) Content Fragments are text-based editorial content that may include some structured data elements associated but considered pure content without design or layout information. Content Fragments are typically created as channel-agnostic content, that is intended to be used and re-used across channels, which in turn wrap the content in a context-specific experience.
Content Fragments, independent of layout, can be used directly in AEM Sites with Core Components or can be delivered in a headless manner to downstream channels.
This video series covers the delivery options for using Content Fragments. Details about defining and authoring Content Fragments can be found here.
- Using Content Fragments on web pages
- Exposing Content Fragments as JSON using AEM Content Services
- Using the Assets HTTP API
Using Content Fragments in Web pages using-content-fragments-in-web-pages
Transcript
Let’s use our content fragments on a webpage in AEM Sites. Let’s head over to AEM Sites and create bio pages for our contributors. We’ll create a new content page and add our content fragment. Note that this template is pre-configured to map - the content fragment assets to the core component content fragment which makes this as easy - as dragging and dropping the content fragment from the - asset finder onto our page. We have two primary ways of surfacing this content - fragment on our website. The first is by rendering a - single multiline text element which enables long form text and editorial style capabilities. Or we can display multiple elements. First, we’ll explore the - single element approach. We’ll select a multi text field, in this case, the biography. When we returned to the - authoring experience, we see the multiline text - element content is displayed and their component drops zones injected between each paragraph. These drop zones allow us - to add components in line with our content fragment content. For instance, we could - add a video component, an image, a pull quote, - or even a promotion. Let’s spice this experience up by adding an image between the paragraphs. This will also help us - understand the benefits of content fragments associated content. When a content fragment is - added to AEM Sites page, and that content fragment - has associated content, we get a new icon in the sidebar. This shows us all of - the associated content for the content fragment, - allowing us to quickly find content that is useful - when exposing our contributor via our web channel. We can add one of these images - by dragging and dropping it into one of our component drop zones. This provides a flexible - authoring experience, but since it’s limited to a - single multiline text element, it’s optimized for content fragments that represent long - form editorial content. For example, this component won’t display the contributors name or occupation since they’re stored in different fields. Let’s check out another method for exposing content - fragments that will allow us to display more elements - from the content fragment.
We’ll create another page - and add a content fragment just like before.
This time we’ll display multiple elements. We can display all elements or pick specific elements to display. Let’s select all of - our available elements.
Upon saving our changes, the - content fragment rendering doesn’t look very impressive, as it produces a simple series - of element titles and values. This is where AEM style - systems can really help out. What we can do is have - our web development team create some simple CSS - that styles this content to make it look quite a bit better. I’ve already installed some custom CSS. So let’s quickly apply it. For this, we’ll register our custom CSS to our content fragment - component via AEM style system.
Now we can apply our custom - style to this content fragment. And there we go, this - looks quite a bit better. You can see that we’re sourcing our data from the content fragment. So we have the full name, we have the asset image that is pointed to by the picture content reference, as well as a two column - style for our bio text.
The same approaches we’ve - explored using AEM Sites pages, can be used to surface content fragments on experience fragments. Which in turn can be used within AEM or outside of it to deliver - managed experiences. - -
Content Fragments can be used on AEM Sites pages, or in a similar fashion, Experience Fragments, using the AEM WCM Core Components’ Content Fragment component.
Content Fragment components can be styled using AEM’s Style System to display the content as needed.
Exposing Content Fragments as JSON exposing-content-fragments-as-json
Transcript
The last way we’ll look at exposing Content Fragments is via AEM Content Services. AEM Content Services is part of AEM’s Fluid Experiences Toolbox and allows content and AEM to be exposed in a standardized JSON format, allowing it to be consumed by any other application or system. So this could be a single page app or a mobile app or even another website. We won’t get into the details of Content Services in this video, but I’ll quickly set up a Content Services end point and expose our Content Fragments as JSON. Lets put a new page template from the We.Retail empty page template type, that will be used to define our end points.
These end point pages are not intended to be accessed as HTML by end users so they don’t need a particular look and feel. These will simply act as end points to serve JSON. Let’s allow some components to be added to these pages, and for our example we want to make sure that the Content Fragment component can be added since this is what we’ll use to expose our content.
Next we’ll head back to the site admin and create a resources that will act as the HTTP end points. This is going to look and feel very similar to a sites webpage buildout. However the intent here is we’re defining Content Service JSON end point resources, and not webpages. So let’s create an API container just for organization purposes.
And under that an athlete’s end point, that will be used to surface our athletes data as JSON.
We can edit this page and add our Content Fragments to it.
And just as we did on our webage configuration, we can configure the Content Fragment component to our liking, ensuring only the appropriate content is rendered to the JSON.
We can add any number of Content Fragments to this page as well as any of the AEM core component or custom components that implement the component exporter interface.
Remember that this page will not be accessed as an HTML document so it’s OK that this content is unstyled.
Once we’ve composed our end point we can review what will be exposed as JSON by making a HTTP GET request to the resource appended with .model.json which is a hook to invoke AEM Content Services on the resource. And there we go, we have or Content Fragment data exported in a normalized JSON format. If we review the JSON, we see we have the element names, values and data types exposed.
AEM Content Services facilitates the creation of AEM Page-based HTTP end-points that rendition content into a normalized JSON format.
The above video uses the Content Fragment Component to expose individual Content Fragments. The Content Fragment List Component is a new component that allows an author to define a query that will dynamically populate the page with a list of Content Fragments. The Content Fragment List component is preferred when multiple Content Fragments need to be exposed.
Example Content Services end-point JSON payload:
athletes.json
Using the Assets HTTP API
Transcript
Adobe Experience Manager includes an out of the box assets, rest API, which allows developers to access and manipulate AEM content directly over an HTTP API. This API, first introduced in AEM6.1 provides CRUD operations or create, read, update, and delete operations against assets in Experience Manager. In AEM 6.5, additional support for content fragments was introduced. The support for content fragments enhances Experience Manager’s content services framework, and provides a new powerful way to access content in a headless manner. Let’s do a quick review of the capabilities of content fragments. So, content fragments are backed by a content fragment model which can be thought of as a data model or template for new content fragments. Experience manager provides a UI to easily manage a content fragment model, allowing developers and authors alike to create robust data models from a series of out of the box data types. So, you can have a very simple model that includes just the single text area, or a more complex model with a number of different fields.
New content fragments are then created from the content fragment model and can be managed through the Experience Manager UI.
Clicking into our content fragment, we have the ability to update and manage any of the fields in our content fragment, we can create different variations of the same fragment, we can also leave annotations and comments as well as associate collections of other assets.
Within AEM, content fragments can be used directly with AEM Sites. Here I have a site’s page that is displaying some store information using three of our content fragments. This is done through a content fragment component which references the content fragment and allows us to choose which elements are going to be displayed.
In addition to managing content fragments through the Experience Manager UI, we can use the assets HTTP API to manipulate content fragments. Taking a look at the API definition, we can see that there are several operations we can perform against content fragments. There’s a GET method to retrieve the content of a content fragment based on a path, a POST method to create a new content fragment. PUT method to update an existing content fragment, and finally a DELETE method to remove a content fragment from a given path. Clicking into any of these operations, we can see an example value, and the structured model that is expected by the API.
So let’s see this in action. I have Postman installed, which is a great program to quickly test out different API calls. I also have a Postman json file that includes some predefined requests to demo the CRUD operations of the API.
So I’ll just go ahead and import this file.
And the first thing we will do is perform a GET request for an existing piece of content. We will request the content for the San Jose store content fragment. Notice that the prefix for the content fragment path starts after slash content slash then.
Hitting Send we can see the response and all the data for this content fragment in json format. Notice that information about variations is also included in this request.
Next, let’s create a new content fragment with a POST operation. Looking at the body, you can see that this will create a new content fragment for a store in Basel. So, we will send the request and we get a response back letting us know that the content fragment has been created with the status code of 201, as well as the path of where the content fragment was created. And, navigating back to AM, we can see that the content fragment has been created.
We can then manage and update the content fragment all within the AEM UI. Let’s do it using the PUT operation of the HTTP API.
So we’ll use the PUT operation and with this request, we will update the location from Switzerland to Swisneyland. So we’ll send that request, and in the response we get a message that lets us know the content has been modified with the status code of 200.
If we navigate back to AEM and refresh the page, we can see our updates.
Now, it’s important when performing an update, you don’t attempt to do a POST instead of a PUT. The API is quite forgiving, and if you attempt to POST to a path that already exists, it’ll attempt to rename the fragment to avoid overwriting an existing one. So, for example, if I resend the POST request, we can see that it actually creates a new content fragment at basel-1 instead of overwriting the existing one.
Lastly, let’s clean up our content fragments by deleting the Basel store.
So we’ll run the DELETE operation to remove the content fragment at the given path.
And let’s clean up that second one as well. I’ll just modify the path to remove that duplicate one at basel-1. And if we return to the AEM UI, you can see that both of these content fragments have been deleted. Like any resource in AEM, content fragments are permission based and security will be an important consideration whether you are consuming or updating content using these API’s. In Postman, I’m authenticating to a local author instance of AEM using basic authentication as admin. If using these API’s with an external application, authentication will most likely need to be handled. OAuth is recommended. Lastly, if you’re using something like a browser-based JavaScript web application to consume content with these API’s, you’ll need to configure Cross Resource Origin Sharing, or CORS, on the AM side to properly make client-side calls. So that’s an overview of the assets HTTP API with added support for content fragments. Thanks.
First introduced in AEM 6.5, is enhanced support for Content Fragments with the Assets HTTP API. This provides an easy way for developers to perform Create, Read, Update, and Delete (CRUD) operations against Content Fragments.
Example POSTMAN Requests:
CRUD-CFM-API-We.Retail.postman_collection.json
Which delivery method to use
Web Channel
The approach to delivering a Content Fragment via a web channel is straightforward by using the Content Fragment component with AEM Sites.
Headless
There are two options for exposing Content Fragment as JSON to support a 3rd party channel in a headless use case:
-
Use AEM Content Services and Proxy API pages (Video #2) when the primary use case is deliver Content Fragments for consumption (Read-only) by a 3rd party channel. The Content Services framework provides more flexibility and options as to what data gets exposed. Developers can also extend the Content Services framework to augment and/or enrich the data.
-
Use the Assets HTTP API (Video #3) when the 3rd party channel needs to modify and/or update Content Fragments. A typical use case is ingesting 3rd party content on an AEM author environment.
Additional Resources additional-resources
To download and install the package below on an AEM 6.4+ instance for the final state from the video series:
aem_demo_fluid-experiencescontent-fragments-100.zip
recommendation-more-help
bb44cebf-d964-4e3c-b64e-ce882243fe4d