Enonic XP 5.2 documentation¶

Project structure¶

The project structure is similar to Maven. Create the folder structure you see below. All are folders except for module.xml and build.gradle:

my-first-module/
  build.gradle
  src/
    main/
      resources/
        module.xml
        cms/
          lib/
          pages/
          parts/
          layouts/
          view/
          assets/
          content-types/
          mixins/
          relationship-types/
          services/

Every file and folder has a specific function and meaning.

build.gradle

Gradle script for building the module. This file describes the actual build process.

module.xml

The module.xml file contains basic information to register the module in Enonic XP. Settings for the module can be defined in the config element and the values for these settings can be updated in the administration console. An example will be presented later in this document. Leave the config element blank for now.

<module>
  <config/>
</module>

cms/lib/

This is the last place the global require javascript-function looks, so it is a good place to put default libraries here.

cms/pages/

Page definitions should be placed here. They will be used to create page templates in the repository.

cms/parts/

Part definitions should be placed here. Parts are objects that can be placed on a page.

cms/layouts/

Layout definitions should be placed here. Layouts are definitions that restricts the placement of parts.

cms/views/

Views can generally be placed anywhere you want, just keep in mind what path to use when resolving them.

cms/assets/

Public folder for external css, javascript and static images.

cms/content-types/

Content schemas-types are placed here. Used to create structured content.

cms/mixins/

Mixin schema-types are placed here. A mixin can be used to add fields to a content-type.

cms/relationship-types/

Relationship-types are placed here. They are used to form relations between contents.

Building the module¶

The project is built using Gradle. Here is a simple build script to build my-first-module.

buildscript {
  repositories {
    jcenter()
    maven {
      url 'http://repo.enonic.com/public'
    }
  }

  dependencies {
    classpath 'com.enonic.xp.gradle:gradle-plugin:1.2.0'
  }
}

apply plugin: 'com.enonic.xp.gradle.module'
version = '1.0.0'

module {
  name = 'com.enonic.xp.modules.mymodule'
  displayName = 'My first module'
}

To build your module, write gradle build on the command line:

$ gradle build

This will produce a jar file that is located inside build/libs folder. That jar file is your build artifact you can install into Enonic XP.

Installing the module¶

After a module is built with Gradle, it must be deployed to your Enonic XP installation. There is not much of a module to build at this point, but you will want to build and check your project after each step of this tutorial. You can refer back to this section whenever you are ready.

To deploy your module, copy the produced artifact to your $XP_HOME/deploy folder:

$ cp build/libs/my-first-module-1.0.0.jar $XP_HOME/deploy/.

We have simplified this process by adding a deploy task to your build. Instead of manually copying in the deploy folder, you can execute gradle deploy instead:

$ gradle deploy

For this to work you have to set XP_HOME environment variable (in your shell) to your actual Enonic XP home directory.

To continuously build and deploy your module on changes, you can use the gradle watch task. This will watch for changes and deploy the changes to Enonic XP. The server will then pick up the changes and reload the module. This is probably the fastest way to develop your module:

$ gradle watch

Setting up a site¶

First, log into the admin console and open the Content Manager app. Then click the New button and scroll down to find and select site from the list. The default username and password is su and password.

Fill in a site name and description and select the modules you want to add to the site. Finally, save the site.

Creating a simple page¶

To create a complete page in Enonic XP, we must grasp three different concepts: the page descriptor, the controller and the view. Start off by making a new folder in the page directory of the module and name it whatever you want. Inside this folder, we will place our controller and page descriptor.

The page descriptor is required to register the page and allows us to set up user input fields to configure the page. It also allows us to describe what regions are available in this page.

Create a page descriptor by making a file named page.xml in folder page/my-first-page.

<page-component>
  <display-name>My first page</display-name>
  <config/>
  <regions/>
</page-component>

Adding a Controller¶

To be able to give a response to a request to this page, we will need to create a controller in the page/my-first-page folder. The controller is written in JavaScript and must be named controller.js. A controller exports a set of methods, one for each HTTP method that should be handled. The handle method has a request object as parameter and returns the result.

// Handles a GET request
exports.get = function(req) {}

// Handles a POST request
exports.post = function(req) {}

Create a simple controller.js file to render an HTML-page when it receives a get request.

exports.get = function(req) {

  return {
    body: '<html><head></head><body><h1>My first page</h1></body></html>',
    contentType: 'text/html'
  };

};

To view this page in Enonic XP, the project must first be built and then deployed. Then open the Content Manager app and find the site (that you created earlier). Click to expand the site and find the Templates folder. Click this folder and select New to create an new Page template. Select the My-first-page from the dropdown on the right as seen below.

The result should look something like this. Give it a name and save.

Rendering a view¶

If you feel like concatenating strings to create an entire webpage is a little too much hassle, Enonic XP also supports views. A view is rendered using a rendering engine; we currently support XSLT, Mustache and Thymeleaf rendering engines. This example will use Thymeleaf.

To make a view, create a file my-first-page.html in the view folder.

<!DOCTYPE html>
<html>
  <head>
  </head>
  <body>
    <h1>My first page, with a view!</h1>
  </body>
</html>

In our controller.js file, we will need to parse the view to a string for output. Here is where the Thymeleaf engine comes in. Using the Thymeleaf rendering engine is easy; here is how we do it.

exports.get = function(req) {

  // Resolve the view
  var view = resolve('/cms/view/my-first-page.html');

  // Define the model
  var model = {
    name: "John Doe"
  };

  // Render a thymeleaf template
  var body = execute('thymeleaf.render', {
    view: view,
    model: model
  });

  // Return the result
  return {
    body: body,
    contentType: 'text/html'
  };

};

Adding dynamic content¶

We can send dynamic content to the view from the controller via the model parameter of the render function. We then need to use the rendering engine specific syntax to render it. The controller file above passed a variable called name and here is how to extract its value in the view using Thymeleaf syntax.

<!DOCTYPE html>
<html>
  <head>
  </head>
  <body>
    <h1>My first page, with a view!</h1>
    <h2>Hello <span data-th-text="${name}">World</span></h2>
  </body>
</html>

More on how to use Thymeleaf can be found in the official Thymeleaf documentation.

Adding regions¶

To be able to add components like images, component parts, or text to our page via the live edit drag and drop interface, we need to create at least one region. To do this we will first modify the page descriptor (page.xml) to support one region called main.

<page-component>
  <display-name>My first page</display-name>
  <config />
  <regions>
    <region name="main"/>
  </regions>
</page-component>

Next, our controller must send the region data to the view.

// Get the current content. It holds the context of the current execution
// session, including information about regions in the page.
var content = execute('portal.getContent');

// Include info about the region of the current content in the parameters
// list for the rendering.
var mainRegion = content.page.regions["main"];

// Extend the model from previous example
var model = {
    name: "Michael",
    mainRegion: mainRegion
};

Finally, we need to modify the view to render all components inside the region. To make live-edit understand that an element is a region, we need an attribute called data-portal-component-type with the value region.

<!DOCTYPE html>
<html>
  <head>
  </head>
  <body>
    <h1>My first page, with a view!</h1>
    <h2>Hello <span data-th-text="${name}">World</span></h2>
    <div data-portal-component-type="region">
      <div data-th-each="component : ${mainRegion.components}" data-th-remove="tag">
        <div data-portal-component="${component.path}" data-th-remove="tag" />
      </div>
    </div>
  </body>
</html>

We can now use the live edit drag and drop interface to drag components onto our page. Lets look into how we can create components.

Creating a part component¶

Creating a component is very similar to creating a page. We need a descriptor, a controller and a view. When they are done, we can add the part component to the page by using drag and drop in live edit.

Start by creating folders part/mypart, and add a part.xml descriptor. This is very similar to our page.xml, the only difference is that a part cannot contain any regions. We want this part to list our favorite things to do, so we will need to configure some input for the part. We will add a text input which can be repeated up to 5 times.

<part-component>
  <display-name>My favorite things</display-name>
  <config>
    <field-set name="things">
      <label>Things</label>
      <items>
        <input type="TextLine" name="thing">
          <label>Thing</label>
          <immutable>false</immutable>
          <indexed>true</indexed>
          <occurrences minimum="0" maximum="5"/>
        </input>
      </items>
    </field-set>
  </config>
</part-component>

Next, create a controller inside the same folder, controller.js.

exports.get = function(portal) {

  // Find the current component from request
  var component = execute('portal.getComponent');

  // Find a config variable for the component
  var things = component.config["thing"] || [];

  // Define the model
  var model = {
    component: component,
    things: things
  };

  // Resolve the view
  var view = resolve('/cms/view/my-favorite-things.html');

  // Render a thymeleaf template
  var body = execute('thymeleaf.render', {
    view: view,
    model: model
  });

  // Return the result
  return {
    body: body,
    contentType: 'text/html'
  };

};

The part needs a root element with the attribute data-portal-component-type. In this case, it will be a part, but we can also resolve it dynamically as explained in the example. The things parameter is basically just JSON data, and we can loop it easily in Thymeleaf and print its value.

<section data-th-attr="data-portal-component-type=${component.type}">
  <h2>A list of my favorite things</h2>
  <ul class="item" data-th-each="thing : ${things}">
    <li data-th-text="${thing}">A thing will appear here.</li>
  </ul>
</section>

The part can now be added to the page via drag and drop. You will be able to configure the part in the context window on the right side of live edit. Here is an image of the result.

Configuring the module¶

Global configuration variables for the site may be defined in the config element of module.xml. Values for these settings can be filled in when you edit the site in the admin console.

<module>
  <config>
    <field-set name="info">
      <label>Info</label>
      <items>
        <input type="TextLine" name="company">
          <label>Company</label>
          <occurrences minimum="1" maximum="1"/>
        </input>
        <input type="TextArea" name="description">
          <label>Description</label>
          <occurrences minimum="1" maximum="1"/>
        </input>
      </items>
    </field-set>
  </config>
</module>

The company and description fields may now be filled out by editing the site. The values will be used in a standard footer for each page.

To use the module configuration values, the controller must retrieve the config element for the module and pass it to the Thymeleaf rendering method.

// Get the current site.
var site = execute('portal.getSite');

// Find the module configuration for this module in current site.
var moduleConfig = site.moduleConfigs['com.enonic.first.module'];

// Get the current content. It holds the context of the current execution
// session, including information about regions in the page.
var content = execute('portal.getContent');

// Include info about the region of the current content in the parameters
// list for the rendering.
var mainRegion = content.page.regions["main"];

// Extend the model from previous example
var model = {
    name: "Michael",
    mainRegion: mainRegion,
    moduleConfig: moduleConfig
};

Now we can update my-first-page.html file to render the configuration values that were passed from the controller.

<!DOCTYPE html>
<html>
  <head>
  </head>
  <body>
    <h1>My first page, with a view!</h1>
    <h2>Hello <span data-th-text="${name}">World</span></h2>
    <footer id="footer">
      <div>
        &copy; 2015
        <span data-th-text="${moduleConfig['company']}">My Company</span> -
        <span data-th-text="${moduleConfig['description']}">All Rights Reserved</span>
      </div>
    </footer>
  </body>
</html>

Creating a layout¶

Layouts are used in conjunction with regions to organize the various component parts that will be placed on the page via live edit drag and drop. Layouts can be dropped into the page regions and then parts can be dragged into the layout. This allows multiple layouts (two-column, three-column, etc.) on the same page and web editors can change things around without touching any code. Layouts can even be nested. Making a layout is similar to making pages and part components. They require a descriptor, a controller, and a view. We will make a two column layout with the widths at 70% and 30%.

The layout descriptor defines regions within the layout where parts can be placed with live edit. First make a new folder layouts/layout-70-30. Within this folder, make a file called layout.xml as seen below.

<layout-component>
  <display-name>70/30</display-name>
  <config/>
  <regions>
    <region name="left"/>
    <region name="right"/>
  </regions>
</layout-component>

Also, create a file called controller.js in the layout-70-30 folder.

exports.get = function(req) {

  // Find the current component.
  var component = execute('portal.getComponent');

  // Resolve the view
  var view = resolve('./layout-70-30.html');

  // Define the model
  var model = {
    component: component,
    leftRegion: component.regions["left"],
    rightRegion: component.regions["right"]
  };

  // Render a thymeleaf template
  var body = execute('thymeleaf.render', {
    view: view,
    model: model
  });

  // Return the result
  return {
    body: body,
    contentType: 'text/html'
  };

};

To make the layout view, create a file in the layout-70-30 folder called layout-70-30.html.

<div class="row" data-th-attr="data-portal-component-type=${component.type}">
  <div data-portal-component-type="region" class="col-sm-8">
    <div data-th-each="component : ${leftRegion.components}" data-th-remove="tag">
      <div data-portal-component="${component.path}" data-th-remove="tag" />
    </div>
  </div>

  <div data-portal-component-type="region" class="col-sm-4" >
    <div data-th-each="component : ${rightRegion.components}" data-th-remove="tag">
      <div data-portal-component="${component.path}" data-th-remove="tag" />
    </div>
  </div>
</div>

Some CSS must be added to style the page for the layout columns to work. Create a css folder inside the assets folder. Boostrap is used in this example so go ahead and download the minified CSS file and put it in the assets/css folder. Now the head element of the view/my-first-page.html file must be updated so that it includes the bootstrap CSS file.

<head>
    <meta charset="utf-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
    <link data-th-href="${portal.assetUrl({'_path=css/bootstrap.min.css'})}" href="../assets/css/bootstrap.min.css" rel="stylesheet"/>
</head>
    

After rebuilding the module, edit the page and click the Insert tab on the right. Then drag and drop a Layout to the main region. Then select the 70/30 layout from the dropdown. Now you can drag an image, text, or part into the layout regions.

Defining a Content-Type¶

Content-Types allow the creation of structured content. They are defined in XML and processed to generate forms for web editors to add content to the site without writing any code.

Create a folder called person in the content-types folder. Then create a file called content-type.xml inside the person folder. Fill it out as follows:

<content-type>
  <display-name>Person</display-name>
  <super-type>system:structured</super-type>
  <is-abstract>false</is-abstract>
  <is-final>true</is-final>
  <is-built-in>false</is-built-in>
  <allow-child-content>true</allow-child-content>
  <form>
    <field-set name="basic">
      <label>Person info</label>
      <items>
        <input type="TextLine" name="first-name">
          <label>First name</label>
          <immutable>false</immutable>
          <indexed>true</indexed>
          <occurrences minimum="1" maximum="1"/>
        </input>
        <input type="TextLine" name="last-name">
          <label>Last name</label>
          <immutable>false</immutable>
          <indexed>true</indexed>
          <occurrences minimum="1" maximum="1"/>
        </input>
        <input type="ImageSelector" name="image">
          <label>Photo</label>
          <immutable>false</immutable>
          <indexed>false</indexed>
          <occurrences minimum="1" maximum="1"/>
        </input>
        <input type="TextArea" name="bio">
          <label>Bio</label>
          <immutable>false</immutable>
          <indexed>true</indexed>
          <occurrences minimum="0" maximum="1"/>
        </input>
      </items>
    </field-set>
  </form>
</content-type>

Save the following image with the name thumb.png and place it in the content-type/person folder. It will become the icon for the person content-type in the admin console.

Adding content¶

Once you rebuild the module, go to the content manager and select New. You will see Person listed as an available content-type in the administration console.

When you create a new Person content then you will see the form that was generated by the XML.

Displaying content¶

Now that a content-type has been defined and a content created, a new component part is needed to display the content. But first, a person content should be prepared in a specific location so that the code below can be copy/pasted and work properly. In the admin console content manager app, right-click on the my-first-site and select new. Then choose folder and name it People. Next, create a new person content in the People folder with the first name Edvard and the last name Munch and type in anything you like for the bio. Upload any image for the picture. Notice the path of this content under the display name is /my-first-site/people/edvard-munch.

Now create a new folder in your project under the parts folder and name it person-show. Now create a part descriptor file named part.xml. This descriptor only needs a display-name for now.

<part-component>
  <display-name>Person</display-name>
  <config/>
</part-component>

Next, create the person-show controller named controller.js.

exports.get = function(req) {

  // Find the current component
  var component = execute('portal.getComponent');

  // Find the right content
  var person = execute('content.get', {
    key: '/my-first-site/people/edvard-munch'
  });

  // Combine the first and last name
  var personName = [
    person.data['first-name'],
    person.data['last-name']
  ].join(' ').trim();

  // Retrieve the image ID from the content used to create a image URL
  var imageId = person.data['image'];

  // Create a URL to the image
  var imageUrl = execute('portal.imageUrl', {
    id: imageId,
    filter: 'scaleblock(400,400)'
  });

  // Create view model
  var model = {
    component: component,
    person: {
      name: personName,
      image: imageUrl,
      bio: person.data['bio']
    }
  };

  // Return the result
  return {
    body: execute('thymeleaf.render', {
      view: resolve('person-show.html'),
      model: model
    }),
    contentType: 'text/html'
  }

};

Now a simple view file called person-show.html can be created to render the content data that is passed from the controller.

<div data-th-attr="data-portal-component-type=${component.type}">
  <p>
    <img class="img-responsive img-circle" data-th-src="${person.image}"
      src="../assets/images/person.jpg" alt="" />
  </p>
  <h3 data-th-text="${person.name}" data-th-remove="tag">Jane Doe</h3>
  <p data-th-text="${person.bio}">Person bio</p>
</div>

Rebuild the project and add the Person part to the page in live edit. This is a very simple example and not a very practical way to retrieve content. Errors would occur if the content name changed (due to the hardcoded content path), or if any of the content fields were missing values. The descriptor and controller will be modified in the next step to use a relationship type that will make the code more dynamic and robust.

Defining a Relationship-Type¶

Relationship-types allow you to create inputs that accept content as the value. These inputs can be used in content-types, module configurations, or the descriptors for component parts and pages. This section will explain how to set up a relationship type and modify the Person component part so that you can pick any Person content in the admin console and it will display correctly.

First create a folder in the relationship-types folder called related-person. Now make a file here called relationship-type.xml.

<relationship-type>
  <display-name>Person</display-name>
  <from-semantic>relates to person</from-semantic>
  <to-semantic>related of person</to-semantic>
  <allowed-from-types/>
  <allowed-to-types>
    <content-type>person</content-type>
  </allowed-to-types>
</relationship-type>

Use the Relationship-Type¶

Now the Person part descriptor can be updated to use the Person relationship type.

<part-component>
  <display-name>Person</display-name>
  <config>
    <input type="Relationship" name="person">
      <label>Person</label>
      <immutable>false</immutable>
      <indexed>false</indexed>
      <occurrences minimum="1" maximum="1"/>
      <config>
        <relationship-type>related-person</relationship-type>
      </config>
    </input>
  </config>
</part-component>

Once this is done, you will be able to choose a Person content for the part in the admin console. But the controller needs some updating to make it work dynamically. The following example shows how to get the related-person of the content.

/*
There are two ways to get content. This way only works when a page
with this `part` supports the content type. Then a URL that leads to
any `Person` content will reach this page and the content is
retrievable with `portal.getContent`. You can see this in action when
you click on a `Person` content in the admin console and it is
previewed in the page.
*/
var content = execute('portal.getContent');

// Find the related person id
var personId = component.config['person'];

// Fetch the actual person content
var person = execute('content.get', {
  key: personId
});

Defining a Mixin¶

Structures of data that are likely to be repeated in different content types can be defined in a single mixin. For example, a standard address form might be used in several content types. Each mixin definition file must be named mixin.xml and it must be placed in its own folder inside the mixins folder.

Go ahead and create the file below in a folder named us-address. The name of this folder will be used later when it is time to implement the mixin in another content type configuration.

<mixin>
  <display-name>U.S. Address format</display-name>
  <items>
    <form-item-set name="address">
      <label>Address</label>
      <immutable>false</immutable>
      <occurrences minimum="0" maximum="0"/>
      <items>
        <input type="TextLine" name="addressLabel">
          <label>Address Label</label>
          <immutable>false</immutable>
          <indexed>true</indexed>
          <occurrences minimum="0" maximum="1"/>
        </input>
        <input type="TextLine" name="addressLine">
          <label>Address Line</label>
          <immutable>false</immutable>
          <indexed>true</indexed>
          <occurrences minimum="1" maximum="2"/>
        </input>
        <input type="TextLine" name="city">
          <label>City</label>
          <immutable>false</immutable>
          <indexed>true</indexed>
          <occurrences minimum="1" maximum="1"/>
        </input>
        <input type="TextLine" name="state">
          <label>State</label>
          <immutable>false</immutable>
          <indexed>true</indexed>
          <occurrences minimum="0" maximum="1"/>
        </input>
        <input type="TextLine" name="zipCode">
          <label>Zip code</label>
          <immutable>false</immutable>
          <indexed>true</indexed>
          <occurrences minimum="1" maximum="1"/>
        </input>
      </items>
    </form-item-set>
  </items>
</mixin>

Using a Mixin¶

Now it is time to use the mixin in a content type. Below is the previous Person content type, modified to include an address. The mixin line as at the bottom.

<content-type>
  <display-name>Person</display-name>
  <super-type>system:structured</super-type>
  <is-abstract>false</is-abstract>
  <is-final>true</is-final>
  <is-built-in>false</is-built-in>
  <allow-child-content>true</allow-child-content>
  <form>
    <field-set name="basic">
      <label>Person info</label>
      <items>
        <input type="TextLine" name="first-name">
          <label>First name</label>
          <immutable>false</immutable>
          <indexed>true</indexed>
          <occurrences minimum="1" maximum="1"/>
        </input>
        <input type="TextLine" name="last-name">
          <label>Last name</label>
          <immutable>false</immutable>
          <indexed>true</indexed>
          <occurrences minimum="1" maximum="1"/>
        </input>
        <input type="ImageSelector" name="image">
          <label>Photo</label>
          <immutable>false</immutable>
          <indexed>false</indexed>
          <occurrences minimum="1" maximum="1"/>
        </input>
        <input type="TextArea" name="bio">
          <label>Bio</label>
          <immutable>false</immutable>
          <indexed>true</indexed>
          <occurrences minimum="0" maximum="1"/>
        </input>
      </items>
    </field-set>
    <x-data mixin="us-address"/>
  </form>
</content-type>

Now you can edit a Person content and see the new address fields.

Overview¶

Years of experience has taught us that traditional approaches to data storage (read SQL) are unsuited for the common requirements of modern cloud-based applications and platforms. A key goal of Enonic XP was to deliver a complete stack - virtually eliminating complex dependencies to 3rd party applications, and minimize requirements to infrastructure.

With the growing popularity of various so-called NoSQL (Not Only SQL) solutions, we evaluated many different technologies and found great inspiration in the following:

Git

• (+) Cherry picking
• (+) Branching
• (+) Pull requests
• (-) Performance search
• (-) Granularity of access (all or nothing)

Java Content Repository

• (+) Hierarchy
• (+) Granularity
• (+) Feature set
• (+) Unstructured
• (-) Performance
• (-) Complexity (not document oriented)
• (-) Attached data model
• (-) Requires additional storage backend

Elasticsearch

• (+) Document oriented
• (+) Scalability
• (+) Performance
• (+) Search
• (+) Aggregations
• (-) Search engine, not a database
• (-) No blob support
• (-) No security
• (-) Creates schemas

We were unable to find any single solution that was sufficiently simple and included our desired feature set - so we decided to build our own; the Enonic Content Repository.

The Enonic Content Repository is a place where you can store data, or more specific: Nodes.

It is built on top of Elasticsearch and exposes many of it’s capabilities in search and aggregations and scalability - but in addition, provides the following capabilities:

• Hierarchical storage model
• Versioning support
• Complete Access Control and security model
• Blob support - using shared filesystem and append-only approach
• Repository and Branch concepts for content staging
• Schemaless - Add any property you like, at any time
• Rich set of value types (HTMLPart, XML, Binary, Reference etc..)
• SQL-like query syntax

The Enonic Content Repository itself contains one or more separate repositories based on the application need. For instance, an application could demand a setup having three repositories - one for application data, one for users and one for logging:

The reasons for having several separated repositories are many, and explained in detail in the Repository below.

Nodes¶

A Node represents a single storable entity of data. It can be compared to a “row” in sql, or a “document” in document oriented storage models. Nodes are, as mentioned in the previous section, stored in a repository.

Every node has:

• a name
• a parent-reference
• an id
• a timestamp
• a (possibly empty) set of Property key/value.

Consider two nodes - one node representing the city “Oslo” and another representing the company, “Enonic”:

The nodes have different properties. There is no schema to a node, so a node property value with the same property-name can have different value-types across nodes.

Property¶

Properties represent a placement of data in a node - following the simple key = value pattern. A property has a path. Elements in the path are separated by . (dot). Every property has also a type. See the complete list of Value Types.

myProperty
data.myProperty
cars.brands.skoda

For a property to be able to hold other properties, it has to be of type Set. In the above samples, data, cars and brands are properties of type Set.

Some characters are illegal in a property key. Here’s a list of illegal characters:

• _ is illegal as the first character, because it is a reserved prefix for System Properties.
• . is illegal as any character, since it is the path separator.
• [ and ] are also illegal as any character. These are used as array index indicators.

Here’s an example of some properties:

first-name = "Thomas"
cities = ["Oslo", "San Francisco"]
city.location = geoPoint('37.785146,-122.39758')
person.age = 39
person.birth-date = localDate("1975-17-10")

Value Types¶

At the core of the node domain are value types. Every property to be stored in a node must have a value type. The value type enables the system to interpret and handle each piece of data specially - applying to both validation and indexing.

All value-types support arrays of values. All elements in an array must be of the same value-type.

Below is a complete list of all supported value-types.

String

A character string.

Index value-type

String

Example

'myString'

GeoPoint

Represents a geographical point, given in latitude and longitude.

Index value-type

GeoPoint

Example

'59.9090442,10.7423389'

Boolean

A value representing true or false.

Index value-type

String

Example

true

Double

Double-precision 64-bit IEEE 754 floating point.

Index value-type

Double

Example

11.5

Long

64-bit two’s complement integer.

Index value-type

Double

Example

1234

Instant

A single point on the time-line.

Index value-type

Instant

Example

2015-03-16T10:00:02Z

LocalDateTime

A date-time representation without timezone.

Index value-type

String

Example

2015-03-16T10:00:02

LocalTime

A time representation without timezone.

Index value-type

String

Example

10:00:03

HTMLPart

Accepts a String containing valid HTML.

Index value-type

String

Example

'<h1>my header</h1>'

XML

Accepts a String containing valid XML.

Index value-type

String

Example

'<property>myPropertyValue</property>'

Reference

Holds a reference to other nodes in the same repository.

Index value-type

String

Example

'0b7f7720-6ab1-4a37-8edc-731b7e4f439e'

BinaryReference

Reference to a binary object.

Index value-type

String

Example

'my-binary-ref'

Set

A special value type that holds properties, allowing nested levels of properties.

System Properties¶

To reduce complexity, we explicitly dropped the use of namespaces. Thus, in order to separate system properties from user defined properties, we reserved _ as a starting character for system properties.

Below are the system properties explained.

_id

Holds the id of the node, typically generated automatically in the form of a UUID.

_name

Holds the name of the node. The name must be unique within its scope (all nodes with same parent).

_parentPath

Reference to parent node path.

_path

The path is resolved from the node name and parent path.

_timestamp

The last change to the node version.

_nodeType

Used to create collections for nodes in a repository.

_versionKey

The id of the node version.

_state

Used for keeping state of a node in a branch.

_permissions_read

The principals that have read access.

_permissions_create

The principals that have create access.

_permissions_delete

The principals that have delete access.

_permissions_modify

The principals that have modify access.

_permissions_publish

The principals that have publish access.

_permissions_readpermissions

The principals that have access to read the node permissions.

_permissions_writepermissions

The principals that have access to change the node permissions.

Repository¶

A repository is a place where nodes can be stored. Data stored in a repository will typically belong to a common domain. Fetches and searches are by default executed against a single repository, so it makes sense to keep data from different domains separated in different repositories. For instance, in the Enonic XP CMS, content and data concerning user management are separated into two repositories. The Content Manager application uses the cms-repo repository, and the User Manager application uses the system-repo repository.

When nodes are stored in the repository, two things happens:

• The node properties are stored in a Blobstore as a node-version. A node-version is an entity representing the properties of the node, without name, parent and other meta-data.
• The node is inserted into a branch. The branch keeps track of a tree-structure referring to node-versions.

A repository will always contain a default branch, called ‘master’. If there is more than one branch, API methods are used for resolving diff between and pushing changes from one branch to another.

Node versions and branches¶

Consider the ‘Oslo’ and ‘Enonic’ nodes from earlier sections:

There will be two node-versions in the repository stored in the blobstore:

A node-version is a representation of a node’s properties. A node-version has no knowledge of name, parent or other meta-data: just the properties of a node. At the same time, the targeted branch (named ‘draft’ in this example) gets two entries:

The node-versions are now a part of a tree-structure, based on the node’s name and parent. If we push the content of branch ‘draft’ to the default branch ‘master’, we end up with something like this:

At the moment, there are two branches pointing to the same node-versions. This means that a single node version can exist in several branches with different structures. Now, consider that the ‘oslo’ - node is updated and stored to the ‘draft’-branch, resulting in a new node-version with the same id and an updated pointer from the branch:

The two branches now point to different node-versions of the ‘oslo’ node. Again, doing a push-operation from ‘draft’ to ‘master’ will result in both nodes pointing to the same node-versions:

Blobstore¶

The blobstore is a file system location defaulted to $XP_HOME/blob. The blobstore itself is split into one directory for nodes and one for binaries.

Content vs Node¶

The foundation of Enonic XP is the Node Domain. In this domain, very general data can be stored and retrieved through the node-API. A node is schema-less, and contains a minimal set of set properties.

A content is a basically a node with a schema and a rich API on top of the node-domain. The schema is defined through Content Types.

Content nodes are stored in a provided Repository called cms-repo, and can be managed in the Enonic XP Content Manager application.

Content manager¶

Enonic XP ships with an application for managing content, called the “Content Manager”.

In the above screenshot, we see a listing of content in the middle, a preview of a site-content in the portal and a faceted search on the right side.

Content repository¶

A built-in content repository called cms-repo is initialized when installing Enonic XP. This is where content is stored when working with content in the Content Manager application or the content-API.

Inside a repository exists something called branches. A branch is a tree-structure containing content. The cms-repo-repository has two branches:

• draft
• master

When working in Content Manager, the content seen is in the branch draft. Content in the portal is served from the master-branch.

Moving content from the draft branch to the master-branch are called publishing.

Content Types¶

Content Types provide developers with a rich, flexible and yet simple way to define interfaces and the resulting data models. Some highlights are:

• A rich set of widgets called Input Types
• Ability to group Input Types for tree-structured data
• Array support for everything
• Automatic generation of content display name from other fields
• Horizontal inheritance through Mixins

Base Content Types¶

Everything has to start somewhere, and for content types this starts with the base types. The base types are all installed and delivered with the system

Content types have a set of special tricks you need to know about:

• Content types are named with their module name, i.e. base:folder, where “base” is the module - but also have a nice display name like “Folder”
• abstract (default: false) means you cannot create content with this content type
• final (default: false) means it is not possible to create content types that “extend” this
• allow-child-content (default: true) if false, it will prevent users to create child items of content of this type.. (i.e. prevents creating child items of images)

Folder (base:folder)¶

• abstract: false
• final: false
• allow-child-content: true

Folders are simply containers for child content, with no other properties than their name and Display Name. They are helpful in organizing your content.

Media (base:media)¶

• abstract: true
• final: false
• allow-child-content: false

This content type serves as the abstract supertype for all content types that in their natural habitate are considered “files”, these are listed below

Unstructured (base:unstructured)¶

• abstract: false
• final: true
• allow-child-content: true

The unstructured content type is a magical content type that permits the creation of any property and structure - without actually defining one first.

Caution

There is currently no UI for unstructured content so they will appear as empty from the admin console.

Structured (base:structured)¶

• abstract: true
• final: false
• allow-child-content: true

This is possibly the most commonly used base type for creating other content type. The structured content type is the foundation for basically any other structured content you can come up with, such as the Person content type above.

Media Content Types¶

• super-type: base:media
• abstract: false
• final: true
• allow-child-content: false

These settings apply to all the listed content types. When uploading a file to Enonic XP it will be transformed to one of the following content-types.

Tip

Enonic XP treats media content pretty much like any other content items - for instance the person, but they all have at least one attachment (namely the file).

Here are the various media content types that also come installed with Enonic XP:

Text (media:text)

Plain text files.

Data (media:data)

Misc binary file formats.

Audio (media:audio)

Audio files.

Video (media:video)

Video files.

Image (media:image)

Bitmap image files.

Vector (media:vector)

Vector graphic files like .svg.

Archive (media:archive)

File archives like .zip, tar and jar.

Document (media:document)

Text documents with advanced formatting, like .doc, .odt and pdf.

Spreadsheet (media:spreadsheet)

Spreadsheet files.

Presentation (media:presentation)

Presentation files like Keynote and Powerpoint.

Code (media:code)

Files with computer code like .c, .pl or .java.

Executable (media:executable)

Executable application files.

Unknown (media:unknown)

Everything else.

<content-type>
  <display-name>Choices</display-name>
  <content-display-name-script>$('firstName', ' ', 'lastName')</content-display-name-script>
  <super-type>base:structured</super-type>
  <is-abstract>false</is-abstract>
  <is-final>true</is-final>
  <allow-child-content>true</allow-child-content>
  <form>
    <input name="choice1" type="ComboBox">
      <label>Choice1</label>
      <occurrences minimum="0" maximum="1"/>
      <config>
          ...
      </config>
    </input>
  </form>
</content-type>

Input Types¶

Each input type holds a specific type of data. A general input type is defined like this:

<input name="name" type="type-name">
  <label>Some label</label>
  <immutable>false</immutable>
  <indexed>true</indexed>
  <occurrences minimum="0" maximum="1"/>
</input>
    

@name

The name attribute is the technical name used in templates and result sets to refer to this value.

@type

The type refers to one of the many input types which are explained below.

label

The label text will become the label for the input field in the editable form of the admin console.

immutable

Immutable is not implemented yet. Setting this value to true will cause the value in such a field to become a constant when it is implemented.

indexed

Indexed in not currently in use either, but required. Thought to indicate if the value should be indexed so it may be searchable, but will most likely be removed.

occurrences

Detailed definition of how many times this field may be repeated inside one content. Set minimum to zero for fields that are not required, and maximum to zero for fields that have no restriction on the number of values.

<input name="name" type="ComboBox">
  <label>Required</label>
  <occurrences minimum="1" maximum="1"/>
  <config>
    <options>
      <option>
        <label>option A</label>
        <value>o1</value>
      </option>
    </options>
  </config>
</input>

<input name="datetime" type="DateTime">
  <config>
    <with-timezone>false</with-timezone>
  </config>
  <label>DateTime (no tz)</label>
  <indexed>true</indexed>
  <custom-text>Custom text</custom-text>
  <occurrences minimum="0" maximum="1"/>
</input>
<input name="requiredDatetime" type="DateTime">
  <config>
    <with-timezone>true</with-timezone>
  </config>
  <label>Required DateTime (with tz)</label>
  <indexed>true</indexed>
  <custom-text>Custom text</custom-text>
  <occurrences minimum="1" maximum="0"/>
</input>

<input name="image" type="ImageSelector">
  <label>Non-required image</label>
  <occurrences minimum="0" maximum="1"/>
</input>

<input name="cited-in" type="ContentSelector">
  <label>Cited In</label>
  <occurrences minimum="0" maximum="0"/>
  <config>
    <relationship-type>system:reference</relationship-type>
    <allow-content-type>citation</allow-content-type>
  </config>
</input>

<input name="radio_selector" type="SingleSelector">
  <label>Radio Selector</label>
  <occurrences minimum="0" maximum="0"/>
  <config>
    <options>
      <option>
        <label>myOption 1</label>
        <value>o1</value>
      </option>
      <option>
        <label>myOption 2</label>
        <value>o2</value>
      </option>
    </options>
    <selector-type>RADIO</selector-type>
  </config>
</input>

<field-set name="metadata">
  <label>Metadata</label>
  <items>
    <input name="tags" type="Tag">
      <label>Tags for tag cloud</label>
      <immutable>false</immutable>
      <indexed>false</indexed>
      <occurrences minimum="0" maximum="5"/>
    </input>
  </items>
</field-set>

<form-item-set name="contact_info">
  <label>Contact Info</label>
  <items>
    <input name="label" type="TextLine">
      <label>Label</label>
      <occurrences minimum="0" maximum="1"/>
    </input>
    <input name="phone_number" type="TextLine">
      <label>Phone Number</label>
      <occurrences minimum="0" maximum="1"/>
    </input>
  </items>
  <immutable>false</immutable>
  <occurrences minimum="0" maximum="0"/>
</form-item-set>

Relationship Types¶

Custom content types may have relationships to each other or other content types. For instance, a person may have an image, or an employee may have a boss, or belong to a department. These relationships must be defined with a specific relationship type, then used in the custom content with an input type ContentSelector. The relationship type definition is an XML file. It must be placed in the folder, cms/relationship-types/[name] and be named relationship-type.xml. Here is an example of a relationship-type:

<relationship-type>
  <display-name>Citation</display-name>
  <from-semantic>citation in</from-semantic>
  <to-semantic>cited by</to-semantic>
  <allowed-from-types/>
  <allowed-to-types>
    <content-type>com.enonic.xp.modules.features:article</content-type>
  </allowed-to-types>
</relationship-type>

from-semantic

Text to describe the “from” relationship.

to-semantic

Text to describe the “to” relationship.

allowed-from-types

Any content type may use this relationship-type.

allowed-to-types

Wherever this relationship-type is used, only an article may be selected.

The content types have the format module-name:content-type-name. The module may be system for built-in types.

Mixins¶

Structures of data that are repeated in many content types, like a set of address fields, or a combobox with a standard set of values, may be defined as mixins and reused in multiple content types. The mixin definition file must be named mixin.xml and placed in the folder cms/mixins/[name]. For example, cms/mixins/us-address/mixin.xml.

<mixin>
  <display-name>U.S. Address format</display-name>
  <items>
    <form-item-set name="address">
      <label>Address</label>
      <immutable>false</immutable>
      <custom-text/>
      <help-text/>
      <occurrences minimum="0" maximum="0"/>
      <items>
        <input type="TextLine" name="addressLine">
          <label>addressLine</label>
          <occurrences minimum="0" maximum="2"/>
        </input>
        <input type="TextLine" name="city">
          <label>City</label>
          <occurrences minimum="1" maximum="1"/>
        </input>
        <input type="TextLine" name="state">
          <label>State</label>
          <occurrences minimum="0" maximum="1"/>
        </input>
        <input type="TextLine" name="zipCode">
          <label>Zip code</label>
          <occurrences minimum="0" maximum="1"/>
        </input>
      </items>
    </form-item-set>
  </items>
</mixin>

<content-type>
  <display-name>Using mixin: us-address</display-name>
  <super-type>base:structured</super-type>
  <is-abstract>false</is-abstract>
  <is-final>true</is-final>
  <is-built-in>false</is-built-in>
  <allow-child-content>true</allow-child-content>
  <form>
    <field-set name="basic">
      <label>Status</label>
      <items>
        <inline mixin="us-address"/> 
      </items>
    </field-set>
  </form>
</content-type>

Content Structure¶

A content has a finite set of possible properties.

_id

The content id.

_name

The content name.

_parent

The parent content path.

attachment

If content contains attachments, a list of attachment-names and properties.

displayName

Name used for display purposes.

contentType

The content schema type.

creator

The user principal that created the content.

createdTime

The timestamp when the content was created.

data

A property-set containing all user defined properties defined in the content-type.

x

A property-set containing properties from mixins.

form

The form defining the input type elements in the content.

language

The locale-property of the content.

modifiedTime

Last time the content was modified.

owner

The user principal that owns the content.

page

The page property contains page-specific properties, like template and regions. This will typically be reference to a page-template that supports the content-type.

site

If content of type portal:site, this will contain site-specific information.

thumbnail

A thumbnail representing the content.

type

A property used to identify content in a node repository.

When creating a content, all defined properties in the content-type are stored under the content’s data property. These properties will get the prefix data.

For example, a content-type article is defined like this:

<content-type>
  <display-name>Article</display-name>
  <super-type>base:structured</super-type>
  <form>
    <input name="title" type="TextLine">
      <label>My property text</label>
      <occurrences minimum="1" maximum="1"/>
    </input>
  </form>
</content-type>

The property “title” is now available in queries under the path data.title:

data.title = 'Fish and cheese'

Content Indexing¶

All content are indexed when stored. The properties of a content is indexed based on a set of rules:

• _id = string
• _name = fulltext
• _parent = string
• attachment = string
• displayName = fulltext
• contentType = string
• creator = string
• createdTime = datetime
• data = type
• x = type
• form = none
• language = string
• modifiedTime = datetime
• owner = string
• page = minimal
• page.regions = none
• site = none
• thumbnail = none
• type = string

Project structure¶

The project structure is similar to Maven. Create the folder structure you see below. All are folders except for module.xml and build.gradle:

my-first-module/
  build.gradle
  src/
    main/
      resources/
        module.xml
        cms/
          lib/
          pages/
          parts/
          layouts/
          view/
          assets/
          content-types/
          mixins/
          relationship-types/
          services/

Every file and folder has a specific function and meaning.

build.gradle

Gradle script for building the module. This file describes the actual build process.

module.xml

The module.xml file contains basic information to register the module in Enonic XP. Settings for the module can be defined in the config element and the values for these settings can be updated in the administration console. An example will be presented later in this document. Leave the config element blank for now.

<module>
  <config/>
</module>

cms/lib/

This is the last place the global require javascript-function looks, so it is a good place to put default libraries here.

cms/pages/

Page definitions should be placed here. They will be used to create page templates in the repository.

cms/parts/

Part definitions should be placed here. Parts are objects that can be placed on a page.

cms/layouts/

Layout definitions should be placed here. Layouts are definitions that restricts the placement of parts.

cms/views/

Views can generally be placed anywhere you want, just keep in mind what path to use when resolving them.

cms/assets/

Public folder for external css, javascript and static images.

cms/content-types/

Content schemas-types are placed here. Used to create structured content.

cms/mixins/

Mixin schema-types are placed here. A mixin can be used to add fields to a content-type.

cms/relationship-types/

Relationship-types are placed here. They are used to form relations between contents.

Building the module¶

The project is built using Gradle. Here is a simple build script to build a module.

buildscript {
  repositories {
    jcenter()
    maven {
      url 'http://repo.enonic.com/public'
    }
  }

  dependencies {
    classpath 'com.enonic.xp.gradle:gradle-plugin:1.2.0'
  }
}

apply plugin: 'com.enonic.xp.gradle.module'
version = '1.0.0'

module {
  name = 'com.enonic.first.module'
  displayName = 'My first module'
}

To build your module, write gradle build on the command line:

$ gradle build

This will produce a jar file that is located inside build/libs folder. That jar file is your build artifact you can install into Enonic XP.

Installing the module¶

After a module is built with Gradle, it must be deployed to your Enonic XP installation. There is not much of a module to build at this point, but you will want to build and check your project after each step of this tutorial. You can refer back to this section whenever you are ready.

To deploy your module, copy the produced artifact to your $XP_HOME/deploy folder:

$ cp build/libs/[artifact].jar $XP_HOME/deploy/.

We have simplified this process by adding a deploy task to your build. Instead of manually copying in the deploy folder, you can execute gradle deploy instead:

$ gradle deploy

For this to work you have to set XP_HOME environment variable (in your shell) to your actual Enonic XP home directory.

To continuously build and deploy your module on changes, you can use the gradle watch task. This will watch for changes and deploy the changes to Enonic XP. The server will then pick up the changes and reload the module. This is probably the fastest way to develop your module:

$ gradle watch

Controllers¶

A controller is a fragment of JavaScript code executed on the server that processes and responds to HTTP requests.

Every page, part, layout and service must have a controller which consists of a JavaScript file named controller.js.

// Handles a GET request
exports.get = function(req) {}

// Handles a POST request
exports.post = function(req) {}

exports.get = function(request) {

  if (request.mode === 'edit') {
    // do something...
  }

  var name = request.params.name;
  log.info('Name = %s', name);

  return {
    body: 'Hello ' + name,
    contentType: 'text/plain'
  };

};

{
  "mode": "edit",
  "uri": "http://enonic.com/my/page",
  "method": "GET",
  "branch": "master",
  "params": {
    "debug": "true"
  },
  "formParams": {
    "user": "dymmy",
    "password": "secret"
  },
  "headers": {
    "Language": "en",
    "Cookies": "mycookie=123; other=abc;"
  },
  "cookies": {
    "mycookie": "123",
    "other": "abc"
  }
}

{
  "status": 200,
  "body": "Hello World",
  "contentType": "text/plain",
  "headers": {
      "key": "value"
  },
  "redirect": "/another/page",
  "pageContributions": {}
}

{
  "body": "<html>...</html>",
  "pageContributions": {
    "headEnd": "value",
    "bodyEnd": [
      "value1", "value2"
    ]
  }
}

Configuring the module¶

Global configuration variables for the site may be defined in the config element of module.xml. Values for these settings can be filled in when you edit the site in the admin console.

<module>
  <config>
    <field-set name="info">
      <label>Info</label>
      <items>
        <input type="TextLine" name="company">
          <label>Company</label>
          <occurrences minimum="1" maximum="1"/>
        </input>
        <input type="TextArea" name="description">
          <label>Description</label>
          <occurrences minimum="1" maximum="1"/>
        </input>
      </items>
    </field-set>
  </config>
</module>

To use the module configuration values, the controller can read the values and use it.

// Get the current site.
var site = execute('portal.getSite');

// Find the module configuration for this module in current site.
var moduleConfig = site.moduleConfigs['com.enonic.first.module'];

Page¶

A page can be composed of parts and layouts or just be a simple page without the compositions. To create a page, you will have to add a descriptor, a controller and optionally - a view.

<page-component>
  <display-name>My first page</display-name>
  <config/>
  <regions/>
</page-component>

// Handles a GET request
exports.get = function(req) {}

// Handles a POST request
exports.post = function(req) {}

exports.get = function(req) {

  return {
    body: '<html><head></head><body><h1>My first page</h1></body></html>',
    contentType: 'text/html'
  };

};

<!DOCTYPE html>
<html>
  <head>
  </head>
  <body>
    <h1>My first page, with a view!</h1>
  </body>
</html>

exports.get = function(req) {

  // Resolve the view
  var view = resolve('/cms/view/my-first-page.html');

  // Define the model
  var model = {
    name: "John Doe"
  };

  // Render a thymeleaf template
  var body = execute('thymeleaf.render', {
    view: view,
    model: model
  });

  // Return the result
  return {
    body: body,
    contentType: 'text/html'
  };

};

<!DOCTYPE html>
<html>
  <head>
  </head>
  <body>
    <h1>My first page, with a view!</h1>
    <h2>Hello <span data-th-text="${name}">World</span></h2>
  </body>
</html>

<page-component>
  <display-name>My first page</display-name>
  <config />
  <regions>
    <region name="main"/>
  </regions>
</page-component>

// Get the current content. It holds the context of the current execution
// session, including information about regions in the page.
var content = execute('portal.getContent');

// Include info about the region of the current content in the parameters
// list for the rendering.
var mainRegion = content.page.regions["main"];

// Extend the model from previous example
var model = {
    name: "Michael",
    mainRegion: mainRegion
};

<!DOCTYPE html>
<html>
  <head>
  </head>
  <body>
    <h1>My first page, with a view!</h1>
    <h2>Hello <span data-th-text="${name}">World</span></h2>
    <div data-portal-component-type="region">
      <div data-th-each="component : ${mainRegion.components}" data-th-remove="tag">
        <div data-portal-component="${component.path}" data-th-remove="tag" />
      </div>
    </div>
  </body>
</html>

Part¶

A part is a building block that can be placed on a page or into a region. As with pages, a part is composed of a descriptor, a controller and and optionally - a view.

The part descriptor is required to register the part and allows us to set up user input fields to configure the part. A part cannot contain any regions.

<part-component>
  <display-name>My favorite things</display-name>
  <config>
    <field-set name="things">
      <label>Things</label>
      <items>
        <input type="TextLine" name="thing">
          <label>Thing</label>
          <immutable>false</immutable>
          <indexed>true</indexed>
          <occurrences minimum="0" maximum="5"/>
        </input>
      </items>
    </field-set>
  </config>
</part-component>

To drive this part, we will also need a controller controller.js.

exports.get = function(portal) {

  // Find the current component from request
  var component = execute('portal.getComponent');

  // Find a config variable for the component
  var things = component.config["thing"] || [];

  // Define the model
  var model = {
    component: component,
    things: things
  };

  // Resolve the view
  var view = resolve('/cms/view/my-favorite-things.html');

  // Render a thymeleaf template
  var body = execute('thymeleaf.render', {
    view: view,
    model: model
  });

  // Return the result
  return {
    body: body,
    contentType: 'text/html'
  };

};

The part needs a root element with the attribute data-portal-component-type. In this case, it will be a part, but we can also resolve it dynamically as explained in the example. The things parameter is basically just JSON data, and we can loop it easily in Thymeleaf and print its value.

<section data-th-attr="data-portal-component-type=${component.type}">
  <h2>A list of my favorite things</h2>
  <ul class="item" data-th-each="thing : ${things}">
    <li data-th-text="${thing}">A thing will appear here.</li>
  </ul>
</section>

The part can now be added to the page via drag and drop. You will be able to configure the part in the context window in live-edit.

Layout¶

Layouts are used in conjunction with regions to organize the various component parts that will be placed on the page via live edit drag and drop. Layouts can be dropped into the page regions and then parts can be dragged into the layout. This allows multiple layouts (two-column, three-column, etc.) on the same page and web editors can change things around without touching any code. Layouts can even be nested. Making a layout is similar to making pages and part components.

Layout contains - like pages and parts - a descriptor, a view and a controller, and should be placed in under the layouts-folder in the module: layouts/<layoutname>/

<layout-component>
  <display-name>70/30</display-name>
  <config/>
  <regions>
    <region name="left"/>
    <region name="right"/>
  </regions>
</layout-component>

exports.get = function(req) {

  // Find the current component.
  var component = execute('portal.getComponent');

  // Resolve the view
  var view = resolve('./layout-70-30.html');

  // Define the model
  var model = {
    component: component,
    leftRegion: component.regions["left"],
    rightRegion: component.regions["right"]
  };

  // Render a thymeleaf template
  var body = execute('thymeleaf.render', {
    view: view,
    model: model
  });

  // Return the result
  return {
    body: body,
    contentType: 'text/html'
  };

};

<div class="row" data-th-attr="data-portal-component-type=${component.type}">
  <div data-portal-component-type="region" class="col-sm-8">
    <div data-th-each="component : ${leftRegion.components}" data-th-remove="tag">
      <div data-portal-component="${component.path}" data-th-remove="tag" />
    </div>
  </div>

  <div data-portal-component-type="region" class="col-sm-4" >
    <div data-th-each="component : ${rightRegion.components}" data-th-remove="tag">
      <div data-portal-component="${component.path}" data-th-remove="tag" />
    </div>
  </div>
</div>

<head>
  <meta charset="utf-8"/>
  <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
  <link data-th-href="${portal.assetUrl({'_path=css/bootstrap.min.css'})}" href="../assets/css/bootstrap.min.css" rel="stylesheet"/>
</head>

Service¶

With services you can create REST-like services without binding it to some content. Place a controller.js file within a named folder under the services folder and this will be accessable with a fixed url:

*/_/service/[module]/[name]

Where module is the module name (without version) and name is the name of the service.

Here’s a simple service that increments a counter and returns it as JSON.

var counter = 0;

exports.get = function(req) {

  counter++;

  return {
    body: {
      time: new Date(),
      counter: counter
    },
    contentType: 'application/json'
  };

};

Rendering a View¶

Instead of composing the HTML output in your controller, it’s much easier to pass the model down to a view. We support pluggable view technologies and support the following out of the box:

• Thymeleaf (see thymeleaf.render)
• Mustache (see mustache.render)
• Xslt (see xslt.render)

Localization¶

Multi-language support for text on a site can be enabled by adding a localization resource bundle to the module. The localization resource bundle contains files with custom localized phrases which can be accessed through localize functions in the “controllers” and “view” files.

To see how this is used in a controller, see i18n.localize function. See localize function on how to use this in the various views.

i18n/phrases.properties
i18n/phrases_en_us.properties
i18n/phrases_no.properties
i18n/phrases_no_nn.properties

phrases[_languagecode][_countrycode][_variant].properties

user.greeting = Hello, {0}!
complex_message = Good to see you. How are you doing?
message_url = http://localhost:8080/{0}
message_multi_placeholder = My name is {0} and I live in {1}
message_placeholder = Hello, my name is {0}.
med_\u00e6_\u00f8_\u00e5 = This contains the norwegian characters æ, ø and å

LA[_CO][_VA]

Overview¶

When searching in Enonic XP, you are searching for nodes, or content if working in context of the CMS-module. This documentation is general and intended for the nodes-domain, but except for some built-in property-values and the addition of some convenience parameters in the content domain, everything is valid for both domains.

In general, the search-API’s deals with a number of basic parameters:

• start
• count
• query
• filter
• aggregations

Query Functions¶

Here’s a description of all functions that can be used in a query.

fulltext(<fields>, <search-string>, <operator>)

fulltext('title^5,description', 'my search string', 'AND')

ngram(<field>, <search-string>, <operator>)

Order Functions¶

Here’s a description of all functions that can be used in order-by clause.

geoDistance(<field>, <location>)

Aggregations¶

An aggregation is a function, or something that is executed, on a collection of search results. The search-results are defined by the query and query-filter of the search request.

For instance, consider a query returning all nodes that has a property “price” less than, say, 100$. Now, we want to divide the result nodes into ranges, say 0-25$, 25-50$ and so on. We also would like to know the average price for each category. This could be done by doing multiple separate queries, and calculate the average manually, but this would be very ineffective and cumbersome. Luckily, aggregations solves these types of problems easily.

In some API functions it’s possible to send in a aggregations expression object. This object is either in Java or a JSON like the following:

"aggregations" : {
  "[name]" : {
    "[type]" : {
      ... body ...
    },
    "aggregations": {
      ... sub-aggregations ...
    }
  }
}

There are two different types of aggregations:

• Bucket aggregations: A bucket aggregation places documents matching the query in a collection - a bucket. Each bucket has a key.
• Metrics aggeregations: A metric aggeregation computes metrics over a set of documents.

Typically, you will divide data into buckets, and then use metric aggregations to calculate e.g average values, sum, etc for each bucket if necessary.

now-1d

2014-12-10T10:00:00Z||-3h+1m

now+1d+30m/m

Querying date and time¶

Querying against date and time-fields may require some knowledge on how data is stored and indexed.

yyyy-MM-dd

myLocalDate = '2015-03-19'
myLocalDate > '2015-03-18'
myLocalDate <= '2015-03-19'

HH:mm[:ss[.SSS]]

09:30
10:00
10:00:30
10:00:30.142

myLocalTime > '09:00'
myLocalTime = '09:36'
myLocalTime = '09:36:00'
myLocalTime LIKE '09:*'
myLocalTime < '09:36:01'
myLocalTime < '09:36:00.1'

myLocalTime > time('9:00')

myLocalTime = time('09:36:00.0')

yyyy-MM-ddTHH:mm[:ss[.SSS]]

myLocalDateTime = '2015-03-19T10:30:00'
myLocalDateTime = dateTime('2015-03-19T10:30')
myLocalDateTime < dateTime('2015-03-19T10:30:00.001')

yyyy-MM-ddTHH:mm[:ss[.SSS]Z

2015-03-19T16:30:20Z
2015-03-19T16:30:20.123Z

yyyy-MM-ddTHH:mm[:ss[.SSS](Z|+hh:mm|-hh:mm)

2015-03-19T16:30:20Z
2015-03-19T16:30:20+01:00
2015-03-19T16:30:20-01:30
2015-03-19T16:30:20.123-01:30

myDateTime = instant('2015-03-19T08:25:00Z')
myDateTime = dateTime('2015-03-19T08:25:00Z')
myDateTime = dateTime('2015-03-19T10:25:00+02:00')
myDateTime = dateTime('2015-03-19T11:25:00+03:00')

Querying paths¶

All nodes have 3 system-properties concerning the node placement in a branch, all of type String:

• _name: The node name without path.
• _parentPath: The parent node path.
• _path: The full path of the node.

Finds node with path /content/mySite/myCategory/myContent.

_path = '/content/mySite/myCategory/myContent'

Finds all nodes with name myContent in a folder named myCategory, e.g /content/test/thisIsMyCategory/myContent and /content/myCategory/myContent.

_name = 'myContent' AND _parentPath LIKE '*myCategory'

Finds all nodes under the path /content/mySite/myCategory including children of children.

_path LIKE '/content/mySite/myCategory/*'

Finds only first level children under the path /content/mySite/myCategory.

_parentPath = '/content/mySite/myCategory'

log¶

This object holds the logging methods. It’s one method for each log level and takes the same number of parameters.

log.debug(message, args)¶

Arguments:	message (string) – Message to log as a debug-level message. args (array) – Optional arguments used in message format.

log.info(message, args)¶

Arguments:	message (string) – Message to log as a info-level message. args (array) – Optional arguments used in message format.

log.warning(message, args)¶

Arguments:	message (string) – Message to log as a warning-level message. args (array) – Optional arguments used in message format.

log.error(message, args)¶

Arguments:	message (string) – Message to log as a error-level message. args (array) – Optional arguments used in message format.

Examples:

// Log a simple message
log.debug('Hello World');

// Log a formatting message
log.debug('Hello %s', 'World');

// Log a formatting message
log.debug('%s %s', 'Hello', 'World');

resolve¶

This function resolves a fully qualified path to a local path based on your current location. It will never check if the path exists, just resolve it. This function supports both relative (with dot-references) and absolute paths.

resolve(path)

Arguments:	path (string) – Path to resolve using current location.
Returns:	The fully qualified resource path of the location.

Examples:

// Absolute path
var path1 = resolve('/cms/views/myview.html');

// Relative path
var path2 = resolve('myview.html');

// Relative path (same as above)
var path3 = resolve('./myview.html');

// Relative path
var path4 = resolve('../myview.html');

require¶

This function will load a javascript and return the exports as object. The function implements parts of the CommonJS Modules Specification.

require(path)

Arguments:	path (string) – Path to the javascript to load.
Returns:	The loaded javascript object exports.

Examples:

// Absolute path
var lib1 = require('/cms/lib/mylib.js');

// Relative path
var lib2 = require('mylib.js');

// Relative path (same as above)
var lib3 = resolve('./mylib.js');

// Relative path
var lib4 = resolve('../mylib.js');

execute¶

This function will execute a Java script command and return any result. It is used to allow the users to execute exposed Java script commands. See Script Commands.

execute(name, params)

Arguments:	name (string) – Name of command to execute. object (params) – Parameters passed down to the execute method.
Returns:	The result of the execute method.

Examples:

// Execute command
var result = execute('thymeleaf.render', {
  view: resolve('myview.html'),
  model: {
    friut: 'apple',
    stock: 10
  }
});

content.get¶

This command fetches a content.

Arguments:

key (string)

Path or id to the content.

branch (string)

Set by portal, depending on context, to either draft or master. May be overridden, but this is not recommended. Default is the current branch set in portal.

Example:

var result = execute('content.get', {
    key: '/my/content'
});

if (result) {
    log.info('Display Name = ' + result.displayName);
} else {
    log.info('Content was not found');
}

Result:

{
  "_createdTime": "1970-01-01T00:00:00Z",
  "_creator": "user:system:admin",
  "_id": "123456",
  "_modifiedTime": "1970-01-01T00:00:00Z",
  "_modifier": "user:system:admin",
  "_name": "mycontent",
  "_path": "/a/b/mycontent",
  "data": {
    "a": [1],
    "b": ["2"],
    "c": [
      {
        "d": [true]
      },
      {
        "d": [true],
        "e": [
          "3",
          "4",
          "5"
        ],
        "f": [2]
      }
    ]
  },
  "displayName": "My Content",
  "draft": false,
  "hasChildren": false,
  "x": {
    "mymodule": {
      "myschema": {
        "a": ["1"]
      }
    }
  },
  "page": {
    "config": {
      "a": ["1"]
    },
    "controller": "mymodule:mycontroller",
    "regions": [
      {
        "components": [
          {
            "config": {
              "a": ["1"]
            },
            "descriptor": "mymodule:mypart",
            "name": "mypart",
            "path": "top/0",
            "type": "part"
          },
          {
            "config": {
              "a": ["1"]
            },
            "descriptor": "mymodule:mylayout",
            "name": "mylayout",
            "path": "top/1",
            "regions": [
              {
                "components": [
                  {
                    "config": {
                      "a": ["1"]
                    },
                    "descriptor": "mymodule:mypart",
                    "name": "mypart",
                    "path": "top/1/bottom/0",
                    "type": "part"
                  }
                ],
                "name": "bottom"
              }
            ],
            "type": "layout"
          }
        ],
        "name": "top"
      }
    ]
  },
  "type": "system:unstructured"
}

content.getChildren¶

This command returns children of a content.

Arguments:

key (string)

Path or id to the parent content.

start (integer)

Start index (used for paging). Default is 0.

count (integer)

Number of contents to fetch. Default is 10.

sort (string)

Sorting expression.

branch (string)

Set by portal, depending on context, to either “draft” or “master”. May be overridden, but this is not recommended. Default is the current branch set in portal.

Example:

var result = execute('content.getChildren', {
    key: '/a/b/mycontent',
    start: 5,
    count: 3,
    sort: '_modifiedTime ASC'
});

log.info('Found ' + result.total + ' number of contents');

for (var i = 0; i < result.contents.length; i++) {
    var content = result.contents[i];
    log.info('Content ' + content._name + ' loaded');
}

Result:

{
  "contents": [
    {
      "_createdTime": "1970-01-01T00:00:00Z",
      "_creator": "user:system:admin",
      "_id": "111111",
      "_modifiedTime": "1970-01-01T00:00:00Z",
      "_modifier": "user:system:admin",
      "_name": "mycontent",
      "_path": "/a/b/mycontent",
      "data": {},
      "displayName": "My Content",
      "draft": false,
      "hasChildren": false,
      "x": {},
      "page": {},
      "type": "system:unstructured"
    },
    {
      "_createdTime": "1970-01-01T00:00:00Z",
      "_creator": "user:system:admin",
      "_id": "222222",
      "_modifiedTime": "1970-01-01T00:00:00Z",
      "_modifier": "user:system:admin",
      "_name": "othercontent",
      "_path": "/a/b/othercontent",
      "data": {},
      "displayName": "Other Content",
      "draft": false,
      "hasChildren": false,
      "x": {},
      "page": {},
      "type": "system:unstructured"
    }
  ],
  "total": 2
}

content.query¶

This command queries content. See Query Language for details.

Arguments:

start (integer)

Start index (used for paging). Default is 0.

count (integer)

Number of contents to fetch. Default is 10.

query (string)

Query expression.

sort (string)

Sorting expression.

aggregations (object)

Aggregations expression.

contentTypes (string[])

Content types to filter on.

branch (string)

Set by portal, depending on context, to either “draft” or “master”. May be overridden, but this is not recommended. Default is the current branch set in portal.

Example:

var result = execute('content.query', {
    start: 0,
    count: 100,
    query: "type = 'article' AND fulltext('myField', 'searching for cheese', 'AND')",
    sort: "modifiedTime DESC, geodistance('p1', 'p2')",
    contentTypes: [
        "mymodule:article",
        "mymodule:comment"
    ],
    aggregations: {
        genders: {
            terms: {
                field: "gender",
                order: "_count asc",
                size: 2
            }
        },
        by_month: {
            date_histogram: {
                field: "init_date",
                interval: "1m",
                minDocCount: 0
            }
        }
    }
});

log.info('Found ' + result.total + ' number of contents');

for (var i = 0; i < result.contents.length; i++) {
    var content = result.contents[i];
    log.info('Content ' + content._name + ' loaded');
}

Result:

{
  "aggregations": {
    "by_month": {
      "buckets": [
        {
          "doc_count": 8,
          "key": "2014-01"
        },
        {
          "doc_count": 10,
          "key": "2014-02"
        },
        {
          "doc_count": 12,
          "key": "2014-03"
        }
      ]
    },
    "genders": {
      "buckets": [
        {
          "doc_count": 10,
          "key": "male"
        },
        {
          "doc_count": 12,
          "key": "female"
        }
      ]
    }
  },
  "contents": [
    {
      "_createdTime": "1970-01-01T00:00:00Z",
      "_creator": "user:system:admin",
      "_id": "111111",
      "_modifiedTime": "1970-01-01T00:00:00Z",
      "_modifier": "user:system:admin",
      "_name": "mycontent",
      "_path": "/a/b/mycontent",
      "data": {},
      "displayName": "My Content",
      "draft": false,
      "hasChildren": false,
      "x": {},
      "page": {},
      "type": "system:unstructured"
    },
    {
      "_createdTime": "1970-01-01T00:00:00Z",
      "_creator": "user:system:admin",
      "_id": "222222",
      "_modifiedTime": "1970-01-01T00:00:00Z",
      "_modifier": "user:system:admin",
      "_name": "othercontent",
      "_path": "/a/b/othercontent",
      "data": {},
      "displayName": "Other Content",
      "draft": false,
      "hasChildren": false,
      "x": {},
      "page": {},
      "type": "system:unstructured"
    }
  ],
  "total": 2
}

content.delete¶

This command deletes a content.

Arguments:

key (string)

Path or id to the content.

branch (string)

Set by portal, depending on context, to either draft or master. May be overridden, but this is not recommended. Default is the current branch set in portal.

Example:

var result = execute('content.delete', {
    key: '/my/content'
});

if (result) {
    log.info('Content deleted');
} else {
    log.info('Content was not found');
}

content.create¶

This command creates a content.

name (string)

Name of content.

parentPath (string)

Path to place content under. Default is ‘/’.

displayName (string)

Display name. Default is same as <name>.

requireValid (boolean)

The content has to be valid to be created. Default is (true).

contentType (string)

Content type to use.

data (object)

Actual content data.

x (object)

eXtra data to use.

branch (string)

Set by portal, depending on context, to either “draft” or “master”. May be overridden, but this is not recommended. Default is the current branch set in portal.

Example:

var result = execute('content.create', {
    name: 'mycontent',
    parentPath: '/a/b',
    displayName: 'My Content',
    draft: true,
    contentType: 'system:unstructured',
    data: {
        a: 1,
        b: 2,
        c: ['1', '2'],
        d: {
            e: {
                f: 3.6,
                g: true
            }
        }
    },
    x: {
        test: {
            a: 1
        }
    }
});

log.info('Content created with id ' + result._id);

Result:

{
  "_id": "123456",
  "_name": "mycontent",
  "_path": "/a/b/mycontent",
  "data": {
    "a": [1],
    "b": [2],
    "c": [
      "1",
      "2"
    ],
    "d": [
      {
        "e": [
          {
            "f": [3.6],
            "g": [true]
          }
        ]
      }
    ]
  },
  "displayName": "My Content",
  "draft": true,
  "hasChildren": false,
  "x": {
    "mymodule:": {
      "test:": {
        "a": [1]
      }
    }
  },
  "page": {},
  "type": "system:unstructured"
}

content.modify¶

This command modifies a content.

key (string)

Path or id to the content.

editor (function)

Editor callback function.

branch (string)

Set by portal, depending on context, to either “draft” or “master”. May be overridden, but this is not recommended. Default is the current branch set in portal.

Example:

function editor(c) {
    c.displayName = 'Modified';
    c.data.a++;
    c.data.z = '99';

    c.x['other'] = {
        name: 'test'
    };

    return c;
}

var result = execute('content.modify', {
    key: '/my/content',
    editor: editor
});

if (result) {
    log.info('Content modified. New title is ' + result.displayName);
} else {
    log.info('Content not found');
}

Result:

{
  "_createdTime": "1970-01-01T00:00:00Z",
  "_creator": "user:system:admin",
  "_id": "123456",
  "_modifiedTime": "1970-01-01T00:00:00Z",
  "_modifier": "user:system:admin",
  "_name": "mycontent",
  "_path": "/a/b/mycontent",
  "data": {
    "a": [2.0],
    "b": ["2"],
    "c": [
      {
        "d": ["true"]
      },
      {
        "d": ["true"],
        "e": [
          "3",
          "4",
          "5"
        ],
        "f": ["2"]
      }
    ],
    "z": ["99"]
  },
  "displayName": "Modified",
  "draft": false,
  "hasChildren": false,
  "x": {
    "mymodule": {
      "myschema": {
        "a": ["1"]
      },
      "other": {
        "name": ["test"]
      }
    }
  },
  "page": {},
  "type": "system:unstructured"
}

portal.getContent¶

This command returns the content corresponding to the current execution context. It is meant to be called from a page, layout or part controller.

Example:

var result = execute('portal.getContent');

log.info('Current content path = ' + result._path);

Result:

{
  "_createdTime": "1970-01-01T00:00:00Z",
  "_creator": "user:system:admin",
  "_id": "123456",
  "_modifiedTime": "1970-01-01T00:00:00Z",
  "_modifier": "user:system:admin",
  "_name": "mycontent",
  "_path": "/a/b/mycontent",
  "data": {
    "a": [1],
    "b": ["2"],
    "c": [{
      "d": [true]
    }, {
      "d": [true],
      "e": ["3", "4", "5"],
      "f": [2]
    }]
  },
  "displayName": "My Content",
  "draft": false,
  "hasChildren": false,
  "x": {
    "mymodule": {
      "myschema": {
        "a": ["1"]
      }
    }
  },
  "page": {
    "config": {
      "a": ["1"]
    },
    "controller": "mymodule:mycontroller",
    "regions": {
      "top": {
        "components": [{
          "config": {
            "a": ["1"]
          },
          "descriptor": "mymodule:mypart",
          "name": "mypart",
          "path": "top/0",
          "type": "part"
        }, {
          "config": {
            "a": ["1"]
          },
          "descriptor": "mymodule:mylayout",
          "name": "mylayout",
          "path": "top/1",
          "regions": {
            "bottom": {
              "components": [{
                "config": {
                  "a": ["1"]
                },
                "descriptor": "mymodule:mypart",
                "name": "mypart",
                "path": "top/1/bottom/0",
                "type": "part"
              }]
            }
          },
          "type": "layout"
        }]
      }
    }
  },
  "type": "system:unstructured"
}