Introduction to Enonic

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:

Selected files from the project structure:

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 to src/main/resources/site/content-types/review/review.xml.
Optionally add an icon by copying or moving the file samples/review/review.svg to src/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: XP Menu → Applications → Install.

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

Get the display name of five items from persons/ folder:

{
 guillotine {
  getChildren(key:"/hmdb/persons" first:5){
    displayName
    _path
  	}
	}
}

Sample response:

{
  "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.

The Person query, this time using path as a variable:

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.

Get display name, and the cast of two movies:

{
  guillotine {
    query(query: "type='com.example.myproject:movie'", first: 2) {
      displayName
      ... on com_example_myproject_Movie {
        data {
          cast {
            actor {
              displayName
            }
            character
          }
        }
      }
    }
  }
}

Sample response

{
  "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.

Name of persons and a link to 400x400 scaled photo

{
  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)")
            }

          }
        }
      }
    }
  }
}

Sample response

{
  "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!