GraphQL Modeling Basics

Learn how to define and use Content Fragments in Adobe Experience Manager (AEM) for use with GraphQL.

In this video you will:

  • Learn how to create and define a Content Fragment Model
  • Learn about the various data types used to build out the Content Fragment Model
  • Understand how the Content Fragment Model drives the GraphQL API
Hello and welcome to the Adobe Experience Manager Headless Series. In today’s series, we’re going to take a look at modeling basics in Adobe Experience Manager by first looking at the WKND Site. The WKND Site is an Adobe Experience Manager sample reference site. It’s ideal for getting started with the basics. Now that we’re on the WKND Site, let’s take a quick look at the Adventure Section.
Now let’s scroll down and the content pages included in the Adventure Section are partially driven by content fragments. Let’s click through.
Now that we’re on the Adventure Content page, let’s scroll down and see which pieces of content are controlled by content fragments. The items on the left: activity, adventure, trip length, group size, difficulty and price are all controlled by content fragments. The area in the center: overview, itinerary and what to bring are also driven by content fragments. Let’s take a look to see how content fragment models and content fragments can help you with your AEM sites and headless use cases.
Now that we’ve seen the WKND Site, let’s take a closer look at content modeling in Adobe Experience Manager. Let’s start by looking at some existing models. First, we’re going to navigate to Tools, then Assets, then Content Fragment Models.
Since we’ve been working with the WKND Site, let’s start there.
The WKND Site has two example models: adventure and article. Let’s continue with our example and explore the adventure content fragment model. The content fragment model editor is where you edit your models. There are a few parts we have to get familiar with first. we have our list of properties, title, description, adventure type, trip length, et cetera. All of these are user definable.
Off to the right, we have the list of data types available to us. There are quite a few available out-of-the-box and we’ll explore those shortly. Let’s take a quick tour of the data types and properties available when building content fragment models.
We’ll start by looking at the single line text. A great example is the title. The single line text is great for forms which require limited, pre-formed text entry. Let’s go ahead and click through and explore some of the properties. We’ll explore four properties. First, we’ll take a look at property name. The property name is important because it does drive the graph QL request response name to used. It also needs to be unique as it uniquely identifies this property for this form within AEM.
Let’s go ahead and take a look at some of the boolean values. The required field indicates that this field is required and the content author needs to fill it in. We can also enforce that this value be unique and that makes sense for a title. Also, most textual entries should be translatable so the translatable flag is enabled.
Our next data type is the multi-line text. This type is suitable for larger textual content entry. The default type property controls the type of content entry allowed by content editor. We have the option of selecting a Rich Text editor, Markdown editor or a simple Plain Text editor. Let’s take a look at another powerful data type. We’ll use the adventure type as an example. The adventure type uses the enumeration. This data type is useful for managing lists of data. Let’s take a look at the Render As. We have a couple of rendering options, check boxes, radio buttons and dropdowns. The options are simple key value pairs. Adding them is quite simple. In this case, we have three: day trip, overnight trip and training session. To add a new one, scroll down to Add Option. We have the ability to enter an option label and an option value. Let’s shift gears and take a look at the number data type. This data type has a few options worth exploring. Let’s start by looking at validation. Since we’re dealing with groups, we should have a sensible number. A group should be one or more people. The validation type offers a few ways to validate the input data. Let’s take a look. We have some options of none, less than or equal to, greater than or equal to, or between. Let’s select greater than or equal to. I will set the minimum to one. We could also control our custom error message. In our case, group has to have at least one person. Let’s continue with our validation example and take a look at the price field. Like before, we’re going to use the single line text and explore the validation type. In this case, the adventure example is using a custom validation type. This will allow us to enter a regular expression to match.
The custom validation regular expression is used to validate U.S. currency but this can be changed for your needs. We can use the description to provide additional formatting details. Let’s take a look at another powerful data type, the content reference. This data type is suitable for bringing content stored in AEM’s Digital Asset Manager. Let’s take a look at the root path. This property is intended to restrict the scope of available assets that a content author can select. Similar to the root path, we have the ability to further constrain the options available for asset selection. We can restrict these by content types. AEM has a large list of available content types and you’re able to select zero or more. In this example, we’re restricting the content type to only images. If your modeling requirements require further restriction, there are some other options available. You can filter by file size, image width and image height.
Now that we have looked at the integration between the content fragment model editor and the DAM, Let’s take a look at another AEM integration. We’ll take a look at AEM tags. The tags data type allows you to use tags within your content model. Let’s take a look. Just like before, the root path is used to restrict the list of available tags that a content editor can use when creating and managing content fragments. In the adventure model, content editors can select up to four seasons. These tags are all available in AEM Tag Manager. Let’s quickly take a tour of some of the remaining data types. We have the boolean to allow you to add simple check boxes to your content models. The date and time data type can be used to add and capture date and time information. We also have a couple of advanced data types that we’ll cover later: fragment reference and the JSON object. Now that we have reviewed some of the basic data types, let’s take a step back and create a content fragment model. Let’s start by accessing the Content Fragment Model Editor.
Now we’re back to the content fragment model’s package at the WKND Site. Let’s click the Create button and create a quick content fragment model. For now, we’ll name it My Model and click the Create button.
To start, let’s drop the single line text data type onto the Form Builder. Since content fragment models are based on your business needs, feel free to add your properties and additional data types as needed. Now that we have a better understanding of content fragment models, let’s take a look at editing and creating content fragments based on content fragment models. Let’s start by navigating to Assets, then Files, then our WKND Site.
Since we’ve been working with Adventures, let’s click through. Now, let’s move into the Tahoe Skiing folder. Notice that we have content fragment called Tahoe Skiing. This content fragment has already been created for you in the WKND Site. Now let’s take a look at some of the validation. Let’s start by looking at group size. If you recall, our validation example required that we had at least one set to the group size. Let’s see what happens when we set it to zero.
As you can see, our custom validation is now presented to the end user. We can do the same thing with our price field. Let’s go ahead and change the price format. The regular expression we came up with required that we expressed our U.S. currency in dollars, the decimal and then the cents. As soon as we make the corrections, the fields go back to normal.
Now that we’ve seen our validation in action, let’s go ahead and create a brand-new content fragment. Creating a content fragment is easy. As long as you’re within Assets, you can go to Create, select Content Fragment and then select the content fragment. In our case, we have Adventure and Article from the WKND Site and the one we created called My Model. This concludes Content Modeling Basics. Stay tuned for future videos on the AEM Headless Video Series. - -