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 git@github.com: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.

4. Start - The application and browse the product catalogue

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

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?

Source: https://github.com/gen­tics/mesh-​vertx-example

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.

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.

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.

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.

Ex­am­ples

• http://lo­cal­host:3000/ → wel­come.hbs
• http://lo­cal­host:3000/Au­to­mo­biles → cat­e­gory → pro­ductList.hbs
• http://lo­cal­host:3000/Au­to­mo­biles/Tesla Road­ster → ve­hi­cle → pro­duct­De­tail.hbs
• http://lo­cal­host:3000/Ve­hi­cle Im­ages/tesla-​roadster.jpg → bi­nary passthru

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

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.

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.

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.