Introduction to Enonic
Contents
An quick introduction to Enonic XP, Content Studio and the GraphQL API.
For an in-depth introduction, check out the Developer 101 tutorial. |
Introduction
This guide will teach you how to:
create a new project from a template
install and use "Content Studio" for editing content
customize your application with new content schemas
access and use the GraphQL API
optionally - deploy your app to a live server
Create project
You will need to install Enonic CLI to complete this guide. |
With Enonic CLI installed, create your project by running the following command. NB! Go with all the default options.
enonic project create -r app-hmdb
The command uses the Headless Movie Data Base app, aka HMDB as a template for your project. By dropping the "-r app-hmdb" option, CLI will list the standard project starters. |
Project structure
In the target folder, you should now have a project structure, looking something like this:
src/
main/
resources/
import (1)
site/ (2)
content-types/ (3)
x-data/ (4)
samples/ (5)
1 | Sample content for Headless Movie Database |
2 | This is where CMS-specific functionality is placed |
3 | Content Types schemas are placed in this directory |
4 | X-data extend existing content types with additional fields |
5 | Code samples that will be used later in this guide |
Building and Deploying
To build and start the app, run this command. It will create and start a sandbox with your app in it. Go with the default options:
enonic project deploy
To verify that your app started successfully, you may find an entre like this within in the sandbox log: 2019-04-09 13:40:40,765 INFO ... Application [com.example.myproject] installed successfully |
For the purposes of this guide, you’ll build and deploy the app manually for each step. If you want to redeploy changes automatically, you can either run in development mode (which will instantly pickup changes to your files), or use continuous build mode, which will compile and re-deploy the full application. Use the following commands respectively: enonic sandbox start --dev enonic project gradle deploy --continuous |
Content Studio
With the sandbox running, you now need to install Content Studio - which is also available as an Enonic app.
Access the XP boot page on http://localhost:8080, and click
Admin Login
. This will bring you to the Admin Dashboard.Install Content Studio from
XP menu → Applications → Install
and find it in the list of apps that appear.Launch Content Studio from
XP menu → Content Studio
.
Sample content
Your freshly created app includes a sample dataset. When the application started, it automatically created a content project called Headless Demo
and imported the HMDB
dataset into it.
Select this project when prompted, and you will see the demo content, similar to the screenshot below:

HMDB is consists of four different content types: Article , Person , Playlist and Movie . Each content type defines a specific form to edit and publish new items. |
Person Content Type
When creating or editing a Person content item, this is what the form looks like in the Content Studio App:

The form definition comes from the project file /src/main/resources/site/content-type/person/person.xml
.
eXtra Data
Below the Person
form fields, you can also see an additional group of fields called Social Media
:

This form step is loaded from a so-called eXtra data schema (x-data for short). The file is located in /src/main/resources/site/x-data/SoMe/SoMe.xml
The benefit of x-data is that it can be re-used across different content types, even content types coming from other applications.
Add a custom content type
To make things more interesting, let’s add the Review
content type.
Copy or move the file
samples/review/review.xml
tosrc/main/resources/site/content-types/review/review.xml
.Optionally add an icon by copying or moving the file
samples/review/review.svg
tosrc/main/resources/site/content-types/review/review.svg
. This will give your reviews a nice icon in Content Studio.Build and deploy your application once more (do this from a new terminal window to avoid stopping the sandbox).
Write A review. From Content Studio, within the HMDB site folder, click new and select
Review
to create a new content item.
GraphQL API
Like Content Studio, the GraphQL API is available via an app.
Install Guillotine app from XP menu → Applications → Install
and find it in the list of apps that appear.

After installing Guillotine, the Content Studio left hand menu will show a new option called Query playground
. This interface gives you the ability to test and play with the GraphQL API.

No Query playground? Then you need to install the "Guillotine" app: |
This API gives you read-access to all content in your project.
Queries can be typed into the left hand panel and executed, with the result in the right-hand panel. Docs are available top right.
Want to know more about GraphQL? After completing the tutorial, feel free to deep dive into the official GraphQL documentation. |
Sample queries
Below are a few examples of queries you can use to access the HMDB
content.
Persons
persons/
folder:
{
guillotine {
getChildren(key:"/hmdb/persons" first:5){
displayName
_path
}
}
}
{
"data": {
"guillotine": {
"getChildren": [
{
"displayName": "Brad Pitt",
"_path": "/hmdb/persons/brad-pitt"
},
{
"displayName": "Keanu Reeves ",
"_path": "/hmdb/persons/keanu-reeves"
},
{
"displayName": "Carrie-Anne Moss ",
"_path": "/hmdb/persons/carrie-anne-moss"
},
{
"displayName": "The Wachowskis",
"_path": "/hmdb/persons/the-wachowskis"
},
{
"displayName": "Bruce Willis",
"_path": "/hmdb/persons/bruce-willis"
}
]
}
}
}
Query variables
GraphQL supports the concept of query variables. Similar to functions you may "re-use" a query by supplying different variables to it - like parameters.
query($path:ID!){
guillotine {
getChildren(key:$path first:5){
displayName
_path
}
}
}
The variables are passed to the query using JSON, this may be added to the API browser from the bottom left corner.
{
"path": "/hmdb/persons"
}
Movies and cast
If you changed the name of your app in the first step: Replace com.example.myproject and com_example_myproject for this query to work. |
{
guillotine {
query(query: "type='com.example.myproject:movie'", first: 2) {
displayName
... on com_example_myproject_Movie {
data {
cast {
actor {
displayName
}
character
}
}
}
}
}
}
{
"data": {
"guillotine": {
"query": [
{
"displayName": "The Godfather",
"data": {
"cast": [
{
"actor": {
"displayName": "Al Pacino"
},
"character": " Michael Corleone"
}
]
}
},
{
"displayName": "The Shawshank Redemption",
"data": {
"cast": [
{
"actor": {
"displayName": "Tim Robbins"
},
"character": "Andy Dufresne"
},
{
"actor": {
"displayName": "Morgan Freeman"
},
"character": "Ellis Boyd 'Red' Redding"
},
{
"actor": {
"displayName": "Bob Gunton"
},
"character": "Warden Norton"
}
]
}
}
]
}
}
}
Person with photo
Set a custom name for your app? You must then replace com.example.myproject and com_example_myproject for this query to work. |
{
guillotine {
query(query: "ngram('_allText', 'morgan') AND type='com.example.myproject:person'", first: 6) {
displayName
... on com_example_myproject_Person {
displayName
data {
photos(first:1){
... on media_Image {
imageUrl(type:absolute scale:"block(400,400)")
}
}
}
}
}
}
}
{
"data": {
"guillotine": {
"query": [
{
"displayName": "Morgan Freeman",
"data": {
"photos": [
{
"imageUrl": "http://localhost:8080/site/default/draft/hmdb/_/image/7ab1f76a-69a1-490f-b505-6eb6773c7cec:603726cc4fa712aa1b70c7eb64e1349f664494c3/block-400-400/morgan-freeman.jpg"
}
]
}
}
]
}
}
}
When deployed to production, these URLs will be aligned with the production endpoint.
API endpoint
So far, you’ve been playing with the API via Content Studio, if you want to access the API’s endpoint directly, its available at respectively
http://localhost:8080/site/hmdb/draft (Drafts, as seen in Content Studio)
http://localhost:8080/site/hmdb/master (the published items).
The API uses HTTP POST method by default, as such - a regular browser will just show you a 404 on this URLs. |
What are sites?
So far, we have used automatically imported content, the HMDB root item has the content type "Site", which is an optional content type used to group content.
You may create multiple sites within a project. Try it yourself:
1 |
Click New at a desired location in the structure, and choose the content type "Site". |
2 |
Add your application to the site ![]() By adding the application to the site, you effectively tell Content Studio that the content types in this app can be used within this site. Apps may also contribute other useful features to the site, such as default preview. |
3 |
Start creating content within the new site |
Sites are optional. You may also add applications to the project root via the settings menu in Content Studio. |
Deploying to Production
To deploy your application to production, you’ll need a server running Enonic XP. The steps below will assume you have already created an account on https://enonic.com/sign-up/cloud-trial.
If you are looking for other hosting options, Enonic XP is open source, and can be deployed anywhere. |
Create a new solution from the Enonic Cloud Console. NB! Choose the "CMS essentials" template
Install your app using the CLI
enonic cloud project install
Alternatively upload the app via UI:
Cloud console → <My solution> → Applications → Install
. The app file can be found in your project folder i.e.build/libs/<myproject>.jar
.Expose your API by creating a Route in Cloud Console.
Specify internal URL as
/site/hmdb/master
Query your published content via the new route endpoint.
Customize your API
The Guillotine app exposes a standard API, but you may also embed and customize the API if needed.
Bon voyage!