Chapter 4 - Defining Content Services Templates

Chapter 4 of the AEM Headless tutorial covers the role of AEM Editable Templates in the context of AEM Content Services. Editable Templates are used to define the JSON content structure AEM Content Services exposes to clients via the composition of Content Services enabled AEM Components.

Understanding the role of Templates in AEM Content Services

AEM Editable Templates are used to define the HTTP end-points that is accessed to expose the Event content as JSON.

Traditionally AEM’s Editable Templates are used to define Web pages, however this use is simply convention. Editable Templates can be used to compose any set of content; how that content is accessed: as a HTML in a browser, as JSON consumed by JavaScript (AEM SPA Editor) or a Mobile App is a function of the how that page is requested.

In AEM Content Services, editable templates are used to define how the JSON data is exposed.

For the WKND Mobile App, we’ll create a single Editable Template which is used to drive a single API endpoint. While this example is simple to illustrate the concepts of AEM Headless, you can create multiple Pages (or Endpoints) each exposing different sets of content to create a more complex, and better organized API.

Understanding the API End-point

To understand how to compose our API endpoint, and understand what content should be exposed to our WKND Mobile App, let us revisit the design.

Events API Page Decomposition

As we can see, we have three logical sets of content to provide to the mobile app.

  1. The Logo
  2. The Tag Line
  3. The list of Events

To do this, we can map these requirements to AEM Components (and in our case, AEM WCM Core Components) in order to expose the requisite content as JSON.

  1. The Logo is surfaced via an Image component
  2. The Tag Line is surfaced via a Text component
  3. The list of Events is surfaced via a Content Fragment List component that in turn, references a set of Event Content Fragments.
To support AEM Content Service’s JSON export of Pages and Components, the Pages and Components must derive from AEM WCM Core Components.
AEM’s WCM Core Components have built-in functionality to support a normalized JSON schema of exported Pages and Components. All of the WKND Mobile components used in this tutorial (Page, Image, Text, and Content Fragment List) are derived from AEM’s WCM Core Components.

Defining the Events API Template

  1. Navigate to Tools > General > Templates > WKND Mobile.

  2. Create the Events API template:

    1. Tap Create in the top action bar
    2. Select the WKND Mobile - Empty Page template
    3. Tap Next in the top action bar
    4. Enter Events API in the Template Title field
    5. Tap Create in the top action bar
    6. Tap Open open the new template for editing
  3. First, we allow the three identified AEM Components we need to model the content by editing the Policy of the Root Layout Container. Ensure the Structure mode is active, select the Layout Container [Root], and tap the Policy button.

  4. Under Properties > Allowed Components search for WKND Mobile. Allow the following components from the WKND Mobile component group so they can be used on the Events API page.

    • WKND Mobile > Image

      • The logo for the the app
    • WKND Mobile > Text

      • The app’s introductory text
    • WKND Mobile > Content Fragment List

      • The list of Event categories available for display in the app
  5. Tap the Done check-mark in the upper right corner when complete.

  6. Refresh the browser window to see newly Allowed Components list in the left rail.

  7. From the Components finder in the left rail, drag in the following AEM Components:

    1. Image for the Logo
    2. Text for the Tag Line
    3. Content Fragment List for the events
  8. For each of the above components, select them and press the unlock button.

  9. However, ensure the layout container is locked to prevent other components from being added, or these three components from being removed.

  10. Tap Page Information > View in Admin to return to the WKND Mobile templates listing. Select the newly created Events API template and tap Enable in the top action bar.

Notice that the components used to surface the content are added to the Template itself, and locked down. This is to allow authors to edit the pre-defined components, but not arbitrarily add or remove components since changing the API itself could break assumptions around the JSON structure and break consuming apps. All APIs need to be stable.

Next steps

Optionally, install the content package on AEM Author via AEM’s Package Manager. This package contains the configurations and content outlined in this and preceding chapters of the tutorial.