Docs Developer Site
Developer 1014 - Content

Content and content types

Contents

In this chapter, we’ll start working with content types in XP. We’ll look at how we create content and how it’s stored, as well as how to create and publish it. To achieve this, we’ll start working with and getting familiar with Content Studio, XP’s content editing suite.

This chapter only gives you a brief introduction to Content Studio and how to use it. For a more comprehensive overview, watch this short video on Content Studio basics or head to the Content Studio reference documentation.

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.

What are content types?

Every content item created in Enonic has a specific content type. The content type defines the data fields (aka properties) that piece of content can and must have.

A JavaScript analogy: If a content type is a JSON schema, the content item is a JSON that matches the schema. Actually, this is not so far from how things actually work - as you will see later 😊

Content types are defined and installed via applications. If you stop or remove an application that contains a content type, you’ll no longer be able to create or edit content of that type.

Task: The artist content type

Now that we know what a content type is, let’s look at how we create them and how we make XP recognize them. We’ll create a content type that contains two input fields. When shown in Content Studio, it will look like this:

A content creation form with name and biography fields
Figure 1. The target for our first content type

  1. To get started, make sure you’re in the project folder (myproject/) that you created in a previous chapter. All paths will be relative to this root folder.

  2. Create a directory for content types: src/main/resources/site/content-types/. XP is quite particular about project folder structure, so you need to put content types right where it expects to find them.

  3. Create a directory called artist in the newly created content-types/ directory. XP expects all content types to have their own directories.

  4. Within the artist directory, create a file called artist.xml. The file name must match the directory name (except for the file extension). The full path to the content type from the project root should thus be src/main/resources/site/content-types/artist/artist.xml.

  5. In the artist.xml file, place the following contents:

    The 'Artist' content type 
    <content-type>
  <display-name>Artist</display-name> (1)
  <description>Information about an artist</description> (2)
  <super-type>base:structured</super-type>
  <form> (3)

    <input name="name" type="TextLine"> (4)
      <label>Name</label>
      <help-text>
        The artist's name (if different from their professional moniker).
      </help-text>
    </input>

    <input type="TextArea" name="about">
      <label>About the artist</label>
    </input>

  </form>
</content-type>
    1 This is what will be displayed in Content Studio when creating new content.
    2 This is an optional description, but it is still recommended to add, as it will make life easier for your editors.
    3 This is where we specify which fields (aka inputs) this content type shall have, basically the form, as seen in Content Studio.
    4 The type attribute specifies what kind of input input the user will see in Content Studio, and the label specifies how the input will be labeled.
    Content types also have a large number of other, optional fields that we won’t get into here. If you’d like to learn more about this, consult the reference documentation.
    XP’s input elements are not the same as HTML input elements. To read more about it, see the chapter on input types. .

  6. Now run:

    enonic project deploy

If everything goes well, you should see your sandbox logs update now. And that’s the basics of creating new content types. Next, let’s turn our eyes to Content Studio and create some actual content!

Content Studio

As mentioned in the introduction, Content Studio is XP’s content management interface. Use it to navigate, create, edit, and publish content and sites. Content Studio also lets you preview pages and other content types that have a visual component.

To access Content Studio from the XP home page (or anywhere in XP), use the top right XP menu and select "Content Studio".

Wanna get a quick overview over Content Studio? Watch this short video on Content Studio basics for a quick overview of how Content Studio works and what you can do with it. If you’d rather just keep reading: we’ll introduce everything as we go along.

Sites

You’re finally ready to create some actual content! With your sandbox up and running, navigate to Content Studio. You should be met with an empty studio that tells you are "wasting this space":

What Content Studio looks like when it’s completely empty.
Figure 2. An empty content studio

Task: Creating a site

Before you can create content, you need a site. Sites are a special content type that ships with Content Studio. It’s one of a very small number of content types that we can place at the very root of the content hierarchy. A site is like a root node that we can nest other content under.

When we create a new site, we can also specify which applications it uses, and that’s where our application comes into play.

  1. To get going, press the "New…​" button in the toolbar. This will bring up a "Create Content" dialog that looks something like this:

    You can also use the keyboard shortcut Alt+n to bring up the "Create Content" dialog.
    The Content Studio create content dialog.
    Figure 3. The Content Studio create content dialog

  2. Select "Site" either by clicking on it, or by navigating to it with your keyboard. You can start typing as soon as the dialog opens to filter the options too!

    When you select it, your browser will take you to a new tab (or window, depending on your browser settings). This is the content creation form (or wizard).

    Creating a new site in content studio. There is a form with site options on the left.
    Figure 4. Creating a new site in Content Studio.

  3. Add the site name in the first field (the one with the <Display Name> placeholder). Being your first site, how about using "My First Site". Notice that when you do this, the path below the input field gets automatically updated to match what you input. You can manually override the path if you wish, but we’ll leave it as is for now.

  4. The description field is used to describe what the site is about. It’s an optional field, so you can leave it blank.

  5. The next field, `Applications, is important. This is where we tell Content Studio what sort of applications the site uses and thus what content types we can create within it. Now, select the "Vanilla Example" app.

Your site form should now look a little something like this.

What the site form looks like after filling out the necessary fields.
Figure 5. A filled out site creation form

To confirm and return to the Content Studio hierarchy, press Save in the menu bar. Feel free to close the tab (you won’t be needing it again).

You can also use the keyboard shortcut ctrl+s on Linux and Windows and ⌘+s on macOS to save your content. Additionally ctrl+enter/⌘+enter saves the content for you and then closes the tab for you.

When you return to the Content Studio hierarchy view, you should now see your site listed. If you expand it, you’ll find that there is also a node called "Templates" underneath it. We can ignore this for now, but we’ll learn more about it later.

Task: Content creation

With the "My First Site" site highlighted, press "New …​" to open the "Create Content" menu again. This time around, you should have some more choices than what you did previously, including our very own content type "Artist"!

The "Create Content" dialog when creating content under the "My First Site" site. It contains more elements than previously, including the "Artist" content type that we created earlier.
Figure 6. The "Create Content" dialog with more content types

However, before we start creating artists, let’s create a folder. Because we’ll be using this site in the coming chapters with more content types, having some hierarchy will make things easier. Choose a new folder and call it "artists".

Next, let’s create a few artists to get used to the workflow. We’ll start with Cardi B.

  1. Select the artists folder (make sure it’s highlighted).

  2. Create a new artist.

  3. Give it the display name "Cardi B".

  4. Use these details to fill in the form:

    Artist details (Cardi B on Wikipedia)
    Name

    Belcalis Marlenis Almánzar

    About

    Belcalis Marlenis Almánzar (born October 11, 1992), known professionally as Cardi B, is an American rapper and songwriter.

    The form for "artist" fully filled out.
    Figure 7. The content form filled out for the artist "Cardi B"

  5. Again, save and close the tab. Now repeat this process for these next two entries. Be aware that Content Studio lets you nest content, so if you try and create new content when "Cardi B" is selected in the hierarchy, it’ll nest the new content under "Cardi B". In our case, though, we want the artists to be nested directly under the current folder, so make sure "artists" folder is selected when you create new content.

    Missy Elliott (Missy Elliott on Wikipedia)
    Name

    Melissa Arnette Elliott

    About

    Melissa Arnette Elliott (born July 1, 1971) is an American rapper, singer, songwriter, and record producer.

    P!nk (P!nk on Wikipedia)
    Name

    Alecia Beth Moore

    About

    Alecia Beth Moore (born September 8, 1979), known professionally as Pink (stylized as P!nk), is an American singer and songwriter.

With these artists created, your content hierarchy should now list the site, the artists folder, and the three artists.

The content hierarchy showing the My First Site site with "Cardi B", "Missy Elliot", "P!nk", and "Templates" listed directly underneath it.
Figure 8. The hierarchy as it should look after creating some content

Content type validation

Enonic provides XML Schema Definitions (XSDs) for text editor integration and validation of your XML schemas. To use it, add the attribute xmlns, xmlns:xsi, and xsi:schemaLocation to your content types as shown below:

Using XSDs for schema validation of a content type definition. 
<?xml version="1.0" encoding="utf-8"?>
<content-type
    xmlns="urn:enonic:xp:model:1.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="urn:enonic:xp:model:1.0 https://raw.githubusercontent.com/enonic/xp/master/modules/core/core-api/src/main/resources/META-INF/xsd/model.xsd">
  <display-name>Content type display name</display-name>

  <!-- rest of content elided for brevity -->

</content-type>

Note that in-editor schema validation depends on whether your text editor supports validating against XSD schemas or not. If your editor doesn’t support it out of the box, it may be available via a Language Server Protocol (LSP) client.

Publishing

You might have noticed the yellow circles with exclamation marks displayed on all the content we’ve been working on, both in the wizard and in the content grid. This is how Content Studio indicates whether something is published or not and whether there are any errors with it. There are four states:

Error (red circle with a cross)

This indicates that there is something wrong with your content. Because XP uses structured content it can also validate content as it is created. If something doesn’t conform to the specified schema (for example: a required field has no value), it will fail to validate and be marked with this symbol.

Work in progress (yellow circle with exclamation mark)

This symbol indicates that this piece of content has unpublished changes. That could be either because this is new content that has never been published, or it could be because there have been changes to this piece of content since it was last published.

Ready for publishing (green circle with a check mark)

This piece of content is marked as ready to be published.

Published (no icon)

This piece of content is published and has not been modified since.

Three pieces of content displaying the three statuses that a piece of content can have
Figure 9. Content status symbols

So what does it mean for content to be published? It doesn’t make much of a difference to us at this stage of the tutorial, but for when you’re working on production systems, it’s very important. So let’s talk briefly about Content Studio’s branching and publishing system.

Content Studio operates with two branches: a draft branch where you work and edit, and a branch that holds the published content, known as the master branch. When you work on something in Content Studio, you’re working on the draft branch. When you publish something, the master branch gets updated with the new content. When you edit that same piece of content in Content Studio again, you’re back to working on the draft, and you have to publish it to see changes to the published content.

To publish a piece of content, right click it and select "Publish".

You can also publish a piece of content by using the keyboard shortcut Ctrl+Alt+P/control+option+P.

Task: publish your site!

Let’s give this publishing thing a try! We’ll publish the whole site at once. Select your site and publish it. You’ll be greeted by the Content Studio publishing wizard.

A dialog with a list of the content to be published and button saying 'publish now'
Figure 10. The Content Studio publishing wizard 🪄

You’ll find that the "Publish now" button isn’t available just yet. For content to be published, you must first mark it as ready. But before we do that, we should also make sure that we select all the content that belongs under the site too. By default, publishing a piece of content doesn’t publish items nested under it. To include nested content, press the "include child items" icon to the left of the content icon (the one that looks sort of like a fork or a three-legged octopus). Next, select the "mark as ready" option from the button dropdown. It’ll mark your content as ready to publish. Now press "publish now".

In short:

  1. Select your site. Publish.

  2. Include child items.

  3. Mark as ready.

  4. Publish 🚀

Task: Data Toolbox

One of the applications we installed previously is Data Toolbox. Data Toolbox provides you with a web interface to visualize and manipulate your XP data. We’ll now see how to inspect our content using Data Toolbox.

  1. Open the XP admin menu and select Data Toolbox. You should have this app installed from when you took the welcome tour.

    The Data Toolbox landing page: grid of icons for administrative actions and accompanying explanations.
    Figure 11. Data Toolbox

  2. Navigate to the "Data Tree" menu. In this menu, the toolbox lists repositories within your XP instance. There are four repositories listed:

    com.enonic.cms.default

    This is the repository that holds your content.

    system.auditlog

    This is where the audit log is stored. The audit log allows you to see a log of everything that’s been done in your XP instance, such as content creation, user administration, etc., and also tells you when it was done and by whom.

    system-repo

    This is where XP stores data about your system, such as external applications and identity data.

    system.scheduler

    This is a separate repository where scheduled jobs are stored (new in 7.7.0).

  3. Navigate through to com.enonic.cms.default.

  4. Next up is a list of branches (as discussed above). As long as you’ve published your content, you can choose either one of these.

  5. Keep navigating further down the tree: [root] → content → my-first-site.

  6. When you’ve reached my-first-site you should see all the content of your site listed. Navigate to artists to find actual pieces of content.

  7. Choose one of your artists and check out both the info view and the JSON view, available via the buttons in the table row.

    The Data Toolbox info view. the view contains options for exporting, moving, and deleting the node, as well as for displaying permissions for the node, versions of the node, and indexing data (and much more).
    Figure 12. The Data Toolbox node info view

  8. To inspect the data associated with the artist, you can select "Display properties", which will bring up data about the node, such as its display name, its owner, when it was created, etc.

    A table with columns 'name', 'index, 'value', and 'type' that describes the node. Example names are 'valid', 'type', 'displayName'.
    Figure 13. The display properties view

  9. Finally, you can navigate to the data property, where you’ll find the data stored on the artist.

    A table showing the data we stored about the artist previously.
    Figure 14. The properties.data view

Inspecting content is only a fraction of what Data Toolbox can do: it’s a versatile and powerful administrative tool, and we’ll see more of it in a later chapter.

Contents