[Blog Post] What caramel really is

  • By Ruchira Wageesha
  • 11 Feb, 2014

For anyone who doesn't know the context of the subject, it is not about the caramel that you taste, it is about a framework developed to write web application using a Jaggery server. Again, if you are not aware of Jaggery, it is a server side JavaScript runtime where you can write your whole web application using JavaScript.

In WSO2, we initiated this new server runtime named Jaggery to take the advantage of JavaScript expertise to write the backend of a web application as well. In today’s web pages, JavaScript can be seen everywhere. Hence, we wanted to take it to the server side, making JavaScript everywhere in the server side as well.

Yes, we made it. Thanks to Jaggery, now JavaScript is everywhere in the server side too. You neither need to learn a completely different language nor to earn a higher skill set to write your web applications. If you know HTML, CSS and JavaScript, then you are ready to go. You can straightaway start writing your whole web application.

We started developing our web apps. Like the frontend JavaScript codes, our server side code base too grew up day by day. Just a single developer couldn't handle it anymore. Many developers engaged on app developments. There were many repeating UI elements with same HTML, CSS and JavaScript. People started duplicating same thing here and there making it very very hard to maintain.

Hence, we tried to come up with a solution for immediate problems that we had. i.e.

  • Reducing UI code duplication
  • Multiple theme support
  • Dynamic theme switching based on tenant etc.
  • Theme customizing and extending

We initially came up with something based on Drupal's UI block concept, multiple theme support and later improved to suit our requirements and Jaggery runtime.

In Jaggery, all requests end up in *.jag files(Note: There is an ongoing development which improve this model by making it more extensible). It goes through url mappings that you defined in jaggery.conf and reaches a *.jag file at the end. In initial caramel version, we didn't want to change that routing mechanism and our only concern was about theming our data. Routing mechanism was out of the scope from initial caramel version and users were allowed go with their preferences.

Caramel introduces multiple themes support where you can switch them dynamically for the request, based on your logic. i.e. Either admin users or tenants might have a completely different theme of their preference. With caramel core, we tries to minimize the conventions/restrictions it imposes on your apps. All you need to do is, passing the data that need to be themed into caramel.render() method from whatever the page you need. After that caramel flow gets the theme for that specific request and allow the theme to render as it wants.

A theme, can decide either to send the data as a JSON or generate HTML from that data and send. Simply, the theme has complete control over what user sees or receives for that request. For the same application, you can define multiple themes based on different templating languages. e.g. One theme based on Handlebars, one theme based on Dustjs etc. or a theme without any templating language at all. This nature allows any developer to re-theme the whole caramel app using his own templating preferences, without touching anything of the web application code.

As I mentioned earlier, caramel core hands everything over to the selected theme and themes have the freedom of rendering those data. For our apps, the templating framework we selected is Handlebars. Hence, we came up with a Handlebars theme engine for caramel core, which enforces a well defined structure for our themes, reuses repeating UI elements across each page etc.

As an example, in one of our web applications, we wanted to include a tag cloud in each page. We could have easily done it with just a Handlebars partial and include it wherever it needs. But that is not the case, tag cloud is not just the HTML, it contains its own CSS and optionally JavaScript codes as well. We will have to always make sure that, those are also included along with tag cloud. Whenever we fix something in the tag cloud, we will have to make sure it is reflected in each place. Hence, we tried to address this aspect through Handlebars engine by virtually grouping HTML, CSS, JavaScript together. i.e. When the tag cloud is added into a page, Handlebars engine will automatically add the relevant CSS and JavaScript too into that page.

That’s a brief information, but not everything about the Handlebars engine that I mentioned here and there. Anyway, if anyone is not happy with the Handlebars engine that we have, they can always write their own engines and themes for the same app, neither modifying existing themes nor web application source.

Let’s say someone wanted to do several minor modifications to one of the existing themes. Then he will have to write a completely new theme with those changes. Fortunately, with caramel, you can create a sub theme with an existing theme. Whatever the files you need to override, can be placed in your sub theme. caramel will first try to load any file from your sub theme and then from the parent theme. With this model, one can customize an existing theme up to some extent even without touching it at all.

I hope, above would be enough for you to understand what and why caramel is. We developed caramel with the experiences and the ideas we had, which neither mean it is right nor the best. Probably you might have better suggestions and experiences. Hence, please contribute your ideas and improvements back to fix what is wrong and what is missing.

You can find the caramel source at [2] and a sample application at [3]. Diagrams at [4] and [5] will help you to understand caramel core and Handlebars engine respectively.

[1] https://jaggeryjs.org

[2] https://github.com/wso2/caramel

[3] https://github.com/ruchiraw/wso2-samples-store

[4] https://raw.github.com/ruchiraw/wso2-samples-store/master/docs/caramel-core.jpg

[5] https://raw.github.com/ruchiraw/wso2-samples-store/master/docs/caramel.handlebars.jpg

Refer to Ruchira's blog