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.
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  and a sample application at . Diagrams at  and  will help you to understand caramel core and Handlebars engine respectively.
Refer to Ruchira's blog