X-data

Contents

X-data (short for eXtra-data) is a way for you to dynamically add extra data to some or all content types belonging to a site. In Content Studio, they’ll be displayed as a separate field set below the content type’s normal fields.

The tasks and examples in this chapter are based on work done in previous chapters (starting with the sandboxes chapter). If you want to follow along with the examples, make sure you’re all caught up.

By configuring your application’s site.xml (src/main/resources/site/site.xml) you can select which X-data schemas to add and to which content types, and whether to make the X-data optional or not. Go to the X-data documentation to read more about how.

As per usual, X-data schemas follow this naming and placement convention (from the project root): src/main/resources/site/x-data/<x-data-name>/<x-data-name>.xml.

X-data share some similarities to mixins (which we saw in the chapter on sets), but they work at a higher level. Both allow you to group fields and add them, but mixins add fields to a content type’s form, while X-data adds fields to a piece of content itself. Further, you configure X-data at a global level, while you configure mixins at a content type level.

Task: add reference data

For the animals we’ve created thus far, we’ve brought in data and images from Wikipedia, but we haven’t indicated this anywhere. If we wanted to indicate where we got some information from, we could do it using X-data. The end result will have extra form fields to add references.

The reindeer content form with an added field set labeled notes at the end of the form.
Figure 1. Animal with an added X-data notes field set.

Your task is:

  • Create a new X-data type. Call it "notes".

  • It should have a single input field, "references", that can have as many occurrences as the user wants

  • Add the X-data to your site, but only to the Animal content type.

  • Try adding some references to one of your animals.

Solution

  1. Create the notes schema in the file src/main/resources/site/x-data/notes/notes.xml. The X-data schema is very similar to the content type schemas we’ve worked with previously, so there’s no real surprises here; just remember to wrap everything in an x-data tag:

    The notes X-data schema
    <x-data>
      <display-name>Notes</display-name>
      <form>
        <input type="TextLine" name="notes">
          <label>Notes</label>
          <occurrences minimum="0" maximum="0" />
        </input>
      </form>
    </x-data>
  2. Add a reference the X-data in your site.xml and tell XP what content types it applies to. To do that, add an x-data tag in site.xml that has a name attribute that matches the name of your X-data (notes). Make sure you add the x-data element before the form and mappings elements.

    Like with fields within a content type form, X-data can be optional or required. If X-data is optional, you need to manually add it to a piece of content. If it is required, it will be added automatically. Note that a piece of X-data being required does not mean that its fields are required. To mark X-data as optional, use optional="true" as described under the X-data configuration section in the XP reference docs.

    The updated site.xml
    <site>
      <x-data name="notes" allowContentTypes="animal"/> (1)
      <form/>
      <mappings>
        <mapping controller="/controllers/graphql.js" order="50">
          <pattern>/api</pattern>
        </mapping>
      </mappings>
    </site>
    1 We use a regular expression to restrict which content types the X-data should apply to. In this case: only to Animal. To reference types outside of the current project, preface the type name with the project name. E.g. com.example.myproject:animal. For content types belonging to the current project, that’s not necessary.
  3. Now, open Content Studio, and add references to your Animal content:

    The content form for Lion with an additional 'References' section below the usual inputs. The first reference, a TextLine input, points to the Wikipedia article.'
    Figure 2. Animal with references added

Headless

When working headlessly, you can easily fetch X-data by querying for the xAsJson field of your content type. This query will return the content’s associated X-data as a JSON object.

Querying for X-data
{
  guillotine {
    query(contentTypes:"com.example.myproject:animal",
      query: "displayName = 'Lion'") {
      xAsJson
    }
  }
}

So if you’ve added some references to your "Lion", you’ll get something like this back. Notice how the JSON data is structured in a hierarchical fashion.

X-data results
{
  "data": {
    "guillotine": {
      "query": [
        {
          "xAsJson": {
            "com-example-myproject": {
              "notes": {
                "references": "Lion (Wikipedia): https://en.wikipedia.org/wiki/Lion"
              }
            }
          }
        }
      ]
    }
  }
}

Contents