Docs Developer Site
Developer 1014 - Content Studio

Content studio and content creation

Contents

In this chapter, we’ll give a short introduction to Content Studio, an app that serves as the main content management interface for XP, providing editors an efficient way of creating, and curating content without technical skills.

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.

Installing Content Studio

Let’s start this chapter by installing Content Studio. In order to do that, access Applications app, click on the header item "install", search for "content studio" and finally click on the green "install" button.

If the app was installed successfully, you should now see it listed in XP menu on your dashboard. Click on it to visit Content Studio’s homepage.

Task: your first project

After visiting Content Studio for the first time on a fresh sandbox, you’ll be welcomed with the following dialog:

Content studio no available projects found dialog
Figure 1. No available projects found dialog

The reason why this dialog shows up is because Content Studio manages content, and content is organized in independent repositories, which are named as a content projects, or simply as projects.

A project offer individual access control and permissions, as well as other settings to toggle features and language(s).

Privileged users can manage projects via Content Studio settings.

Now, head back to the wizard dialog to create your first project:

Content studio project creation wizard walkthrough.
Figure 2. Creating your first project

Assiging an app to a project

Content Studio is a powerful app with a lot of features, and one of its main goal is to provide an awesome user experience for creating and curating content.

Content is defined through content types (a concept we’ll introduce in the next section), which are defined and installed via applications.

Therefore, if we want to enable Content Studio to manage a specific type of content, we need to access content studio in a project which has an app assigned to it, and in this app, this specific content should defined via a content type.

With all this in mind, note that one of the last steps on the previous creation wizard was to assign your app to the project. If you followed along, you should have your app assigned to the your first project, and in case you missed it, no worries, let’s assign it to the created project:

  1. On the green widget sidebar, click on settings

  2. Double click on the project you just created to edit it

  3. Scroll down and on the "Applications" section, select the application you’ve previously deployed to this sandbox

Content studio assigning apps to projects walkthrough.
Figure 3. Assigning your first app to your first project

Apps vs projects

We’ve reached a certain point in this guide where its worth giving a section to reiterate the differences between:

  1. XP project folder and its files

  2. XP app

  3. Content Studio project

A "XP project folder and its files" is the folder containing the files needed in order to create a XP app. In the previous section, this was automatically generated for us when we picked the "Vanilla starter" using the command enonic project create.

A "XP app" is the .jar file that is generated when you run the command enonic project build on the project root folder.

A "Content Studio project", as explained in the section Task: your first project above, is a repository to store content, and the content creation is enabled through the apps you assign to a project.

In summary, you can have the following flow in mind:

Simplied flow explaining the difference between an Enonic XP project folder and its files
This flow is super simplified and there are a lot of details to each one of those boxes, but it should be sufficient to explain the main difference between those ideas and how they connect to eachother.

From now on, we’ll use the term "project" to refer to a "XP project folder and its files" and also to a"Content Studio project", since it can be easily distinguished by the context in which te term is used.

We believe that this will help to avoid any confusion from your side. Now, back to work!

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, then 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!

As mentioned before, content types are defined and installed via applications. If you unassign an application from the project you’re currently working on, you’ll no longer be able to create or edit content of that type.

Task: your first content type

Now that we know what a content type is, let’s look at how we create 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 4. The target for your first content type

Back to your preferred editor, 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.

  1. 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.

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

  3. 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 be src/main/resources/site/content-types/artist/artist.xml.

  4. 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 .

  5. Now run:

  enonic project dev

This command will watch changes under myproject/ and redeploy as needed.

Make sure you’re already running your sandbox with the --dev flag in another terminal, otherwise running enonic project dev will start the sandbox in detached mode, so you’ll lose logs. More on cli’s dev command here.

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 go back to Content Studio and create some actual content!

Task: your first content creation

Go back to content studio and make sure you are on the project you’ve created on the beginning of this chapter.

Press "New …​" to open the "Create Content" menu. You should see a content type "Artist".

This content type is only visible there because of the updates we did to the app, i.e, your app is responsible to be delivering a artist structure in which content studio can start to actually create content.
The "Create Content" dialog when creating content under the created project. It contains elements, including the "Artist" content type that we created earlier.
Figure 5. The "Create Content" dialog with the artist available for content creation

However, before we start creating artists, let’s create a folder.

Since we’ll be using this project in the coming chapters with more content types, having some hierarchy will make things easier. Create 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 6. 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 this 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 artists folder and the three artists.

The content hierarchy showing artists folder with "Cardi B", "Missy Elliot" and "P!nk" listed directly underneath it.
Figure 7. 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 your content

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

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 when you’re working on production systems, it’s very important. So let’s talk briefly about Content Studio’s branching and publishing system.

Branches

Content Studio operates with two branches:

  • draft branch, where you work and edit;

  • master branch, holds the published content.

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.

Data Toolbox

We’ll now install and give a brief introduction to the Data Toolbox app, so make sure to install it directly from the Applications app (same flow as installing Content Studio or any other app).

Data Toolbox provides you with a web interface to visualize and manipulate your XP data. We’ll now see how to inspect content using Data Toolbox.

  1. Open the XP 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 8. 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.my-first-project

    This is the current repository that holds your content.

    com.enonic.cms.default

    This is the default repository.

    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.my-first-project.

  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.

  6. When you’ve reached content 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 9. 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 10. 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 11. 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

Contents