A scoop of Caramel

How Does WSO2 Governance Store pages are Rendered?

A scoop of caramel on top of jaggery may not always be a delicious serving, “Cause you know sometimes words have two meanings”. True that, when specially Caramel is a JS framework that is focused on extendibility of web apps and jaggery is what it lies on from the backend. ;)

Both Jaggery.js and Caramel were developed at WSO2 with acquiescence to Carbon framework focusing on providing more extendibility to web apps running inside a carbon server. (All wso2 products run on top of a carbon server and you can deploy jaggery web apps effortlessly by simply dropping them inside the directory ./repository/deployment/server/jaggeryapps). New interfaces of wso2 products (Governance Center, API Publisher/Store, Business Process Center) are packed as jaggery apps. This post will give you an intuition to few important caramel functions and process of rendering templates.

In Governance Center — Store, (More or less all the other products follow a similar approach in their publisher and store apps) there are two main pages which display assets. One is top-assets page and the other is list page.

top-assets page is the main page which displays the recent assets with a categorization when you access the store url (Figure 1). List page is loaded once you click on a asset type from the navigation menu. It has the url format of store/assets/<rxt-type>/list. (Figure 2).

Read my other post about rxt types from here.

List page is constructed with a partial named "assets.hbs" under $GREG_HOME/repository/deployment/server/jaggeryapps/store/themes/store/partials.

It is rendered using caramel.render() function located at .store/themes/store/js/assets.js. Once the JSON data for assets are received, it is passed along with the partial reference to the caramel.render() function, then which returns the html content that needs to be appended to the HTML div.

caramel.data({
    title : null,
    body : ['assets']
}, {
    url : url,
    success : function(data, status, xhr) {});

caramel.data() accepts 2 parameters namely {areas} and {options}.

The area object specifies to which partial do we require data for and the later is passed for $.ajax() method and the callbacks can be defined according to jquery ajax callbacks.

caramel.handlebars.js at the server side handles the request and it returns a data object which has following attributes.

The returning object contains all the details about required partials to render the page such as resulting assets, current user details, search bar history and all other details.

Once the data is received and if there is more than one partial to be rendered, caramel.partials() function is invoked with reference to the list of partials at the return data, which typically wrapped at data._.partials. Then the caramel.render is passed as a callback in which the real compilation of partials take place. caramel.render() requires the partial to to rendered and then the reference to the context object of the returned json object, which typically is data.assets.context and a callback function to which the html content is returned. Once the html content for the partial is returned we can manipulate the current DOM object with the new HTML content by simply writing to the required dev. By that way we can perform single page loading with caramel framework.

Typically a handlebars partial looks like the following.

Syntaxes with {{}} are handlebars notations and they are resolved by the caramel.render function once we provide the JSON with which the data to resolve those handlebars placeholders are available. i.e.: {{rxt.pluralLabel}} can be found under the rxt attribute of the returning object.

These partials are pluggable templates and can be used to improve the extendibility of the applications. The {{>assets}} notation implies assets.hbs is plugged in right after line #30. Required scripts such as JavaScripts, CSS and other files such as fonts are plugged to the page using helper files that reside next to the partials. The helpers describes which resources needs to included to the parent file when it is loaded. Therefore, once a partial is loaded, its resources are readily available on the parent DOM. Following is a helper file for the top-assets page. Importantly, the helper file needs to have the same name as the partial. When the partial is required, caramel loads its resources by looking into the helper file. (Important not to confuse these helpers with handlebars helpers)

Concisely, this is a very shallow write-up on caramel page rendering on wso2 products. Here, we have only covered how the partials are rendered on client side. There can be situations we need to resolve partials from the server side, especially, when certain handlebars helpers are not available on the client side.

Fingers crossed to cover that part in my next post!

Cheers!