Data-driven Apps made easy with Vert.x 3.4.0 and headless CMS Gentics Mesh

In this ar­ti­cle, I would like to share why Vert.x is not only a ro­bust foun­da­tion for the head­less Con­tent Man­age­ment Sys­tem Gen­tics Mesh but also how the re­cent re­lease 3.4.0 can be used to build a template-​based web server with Gen­tics Mesh and han­dle­bars.

A head­less CMS fo­cuses on de­liv­er­ing your con­tent through an API and al­lows ed­i­tors cre­at­ing and man­ag­ing that data through a web-​based in­ter­face. Un­like a tra­di­tional CMS, it does not pro­vide a specif­i­cally ren­dered out­put. The fron­tend part (the head) is lit­er­ally cut off, al­low­ing de­vel­op­ers cre­ate web­sites, apps, or any other data-​driven projects with their favourite tech­nolo­gies.

Vert.x 3.4.0 has just been re­leased and it comes with a bunch of new fea­tures and bug fixes. I am es­pe­cially ex­cited about a small en­hance­ment that changes the way in which the han­dle­bars tem­plate en­gine han­dle their con­text data. Pre­vi­ously it was not pos­si­ble to re­solve Vert.x ‘s JsonOb­jects within the ren­der con­text. With my en­hance­ment #509 - re­leased in Vert.x 3.4.0 - it is now pos­si­ble to ac­cess nested data from these ob­jects within your tem­plates. Pre­vi­ously this would have re­quired flat­ten­ing out each ob­ject and re­solv­ing it in­di­vid­u­ally, which would have been very cum­ber­some.

I’m going to demon­strate this en­hance­ment by show­ing how to build a prod­uct cat­a­logue using Vert.x to­gether with han­dle­bars tem­plates to ren­der and serve the web pages. The prod­uct data is man­aged, stored and de­liv­ered by the CMS server as source for JSON data.

Clone, Import, Download, Start - Set up your product catalogue website quickly

Let’s quickly set up every­thing you need to run the web­site be­fore I walk you through the code.

1. Clone - Get the full Vert.x with Gentics Mesh example from Github

Fire up your ter­mi­nal and clone the ex­am­ple ap­pli­ca­tion to the di­rec­tory of your choice.

git clone [email protected]:gentics/mesh-vertx-example.git

2. Import - The maven project in your favourite IDE

The ap­pli­ca­tion is set up as a maven project and can be im­ported in Eclipse IDE via File → Im­port → Ex­ist­ing Maven Project

3. Download  -  Get the headless CMS Gentics Mesh

Down­load the lat­est ver­sion of Gen­tics Mesh and start the CMS with this one-​liner

java -jar mesh-demo-0.6.xx.jar

For the cur­rent ex­am­ple we are going to use the read-​only user cre­den­tials (we­b­client:we­b­client). If you want to play around with the demo data you can point your browser to http://lo­cal­host:8080/mesh-​ui/ to reach the Gen­tics Mesh user in­ter­face and use one of the avail­able demo cre­den­tials to login.

Gentics Mesh User Interface

4. Start - The application and browse the product catalogue

You can start the Vert.x web server by run­ning

That’s it - now you can ac­cess the prod­uct cat­a­logue web­site in your browser: http://lo­cal­host:3000

Why Vert.x is a good fit for Gentics Mesh

Be­fore dig­ging into the ex­am­ple, let me share a few thoughts on Vert.x and Gen­tics Mesh in com­bi­na­tion. In this ex­am­ple Vert.x is part of the fron­tend stack in de­liv­er­ing the prod­uct cat­a­logue web­site. But it might also be of in­ter­est to you that Vert.x is also used at the very heart of Gen­tics Mesh it­self. The Gen­tics Mesh REST API end­points are built on top of Vert.x as a core com­po­nent.

The great thing about Vert.x is that there are a lot of de­fault im­ple­men­ta­tions for var­i­ous tasks such as au­then­ti­ca­tion, data­base in­te­gra­tion, mon­i­tor­ing and clus­ter­ing. It is pos­si­ble to use one or more fea­tures and omit the rest and thus your ap­pli­ca­tion re­mains light­weight.

Curious about the code?


Now that every­thing is up and run­ning let’s have a de­tailed look at the code.

A typ­i­cal de­ploy­ment unit for Vert.x is a ver­ti­cle. In our case we use the ver­ti­cle to bun­dle our code and run the web server within it. Once de­ployed, Vert.x will run the ver­ti­cle and start the HTTP server code.

...waiting for Gist...

The Gen­tics Mesh REST client is used to com­mu­ni­cate with the Gen­tics Mesh server. The Vert.x web li­brary is used to set up our HTTP Router. As with other rout­ing frame­works like Silex and Ex­press, the router can be used to cre­ate routes for in­bound HTTP re­quests. In our case we only need two routes. The main route which ac­cepts the re­quest will uti­lize the Gen­tics Mesh We­b­root API End­point which is able to re­solve con­tent by a pro­vided path. It will ex­am­ine the re­sponse and add fields to the rout­ing con­text.

The other route is chained and will take the pre­vi­ously pre­pared rout­ing con­text and ren­der the de­sired tem­plate using the han­dle­bars tem­plate han­dler.

...waiting for Gist...

First we can han­dle var­i­ous spe­cial re­quests path such as ”/” for the wel­come page. Or the typ­i­cal fav­i­con.ico re­quest. Other re­quests are passed to the We­b­root API han­dler method.

...waiting for Gist...

Once the path has been re­solved to a We­b­RootRe­sponse we can ex­am­ine that data and de­ter­mine whether it is a bi­nary re­sponse or a JSON re­sponse. Bi­nary re­sponses may occur if the re­quested re­source rep­re­sents an image or any other bi­nary data. Re­solved bi­nary con­tents are di­rectly passed through to the client and the han­dle­bars route is not in­voked.


JSON re­sponses on the other hand are ex­am­ined to de­ter­mine the type of node which was lo­cated. A typ­i­cal node re­sponse con­tains in­for­ma­tion about the schema used by the node. This will ef­fec­tively de­ter­mine the type of the lo­cated con­tent (e.g.: cat­e­gory, ve­hi­cle).

...waiting for Gist...

Mesh Schemas

The demo ap­pli­ca­tion serves dif­fer­ent pages which cor­re­spond to the iden­ti­fied type. Take a look at the tem­plate sources within src/main/re­sources/tem­plates/ if you are in­ter­ested in the han­dle­bars syn­tax. The tem­plates in the ex­am­ple should cover most com­mon cases.

Handlebars Template Overview

The Mesh REST Client li­brary in­ter­nally makes use of the Vert.x core HTTP client.

Rx­Java is being used to han­dle these async re­quests. This way we can com­bine all asyn­chro­nously re­quested Gen­tics Mesh re­sources (bread­crumb, list of prod­ucts) and add the loaded data into the rout­ing con­text.

The Vert.x ex­am­ple server loads JSON con­tent from the Gen­tics Mesh server. The JsonOb­ject is placed in the han­dle­bars ren­der con­text and the tem­plate can ac­cess all nested fields within.

This way it is pos­si­ble to re­solve any field within the han­dle­bars tem­plate.

...waiting for Gist...

That’s it! Fi­nally, we can in­voke mvn clean pack­age in order to pack­age our web­server. The maven-​shade-plugin will bun­dle every­thing and cre­ate an ex­e­cutable jar.

What’s next?

Fu­ture re­leases of Gen­tics Mesh will re­fine the Mesh REST Client API and pro­vide a GraphQL which will re­duce the JSON over­head. Using GraphQL will also re­duce the amount of re­quests which need to be is­sued.

Thanks for read­ing. If you have any futher ques­tions or feed­back don’t hes­i­tate to send me a tweet to @Jotschi or @gen­tic­smesh.

Next post

Scala is here

The rise of Scala as one of the most important languages on the JVM caught many (me included) by surprise. This hybrid of functional and imperative paradigms struck a chord with many developers.

Read more
Previous post

Vert.x 3.4.0 is released!

Vert.x 3.4.0 has just been released with many new exciting features!

Read more
Related posts

Things to keep in mind concerning CSRF attacks

Eclipse Vert.x like most frameworks provides an anti-CSRF defense. However, no framework can prevent all attack vectors that exist in the web. Therefore, developers need to be aware of some dangers and common attack vectors concerning CSRF defenses.

Read more

Real-time bidding with Websockets and Vert.x

The expectations of users for interactivity with web applications have changed over the past few years. Users during bidding in auction no longer want to press the refresh button.

Read more

An Introduction to the Vert.x Context Object

Under the hood, the vert.x Context class plays a critical part in maintaining the thread-safety guarantees of verticles. Most of the time, vert.x coders don't need to make use of Context objects directly.

Read more