Getting Started with WSO2 Caramel Framework
During my internship at WSO2, I came across WSO2’s Jaggery framework. This open-source framework enables Developers to write all aspects of their web application; the front-end UI, the back-end logic and even the communication and persistence mechanisms, purely based on Javascript. As you might already know, a modern web programme uses Javascript up to a considerable extent at the front-end. Also, you can use Javascript to work out your magic at the server side as well! So, without getting bogged down on learning various technologies to implement the server-side logic of your web application, if you know HTML, CSS and Javascript, you can simply start writing a web application with the help of Jaggery.
However, as the development proceeds, the server-side Javascript code will become too big to be handled by a single developer. Thereafter, many developers will be involved in the development and chances are there will be duplication of the same code. To avoid this kind of a situation, WSO2 Caramel was introduced. It is a MVC framework that further simplifies developing web applications using Jaggery.
In this blog post, I will be creating a simple hello world application using Caramel.
I will be using WSO2’s Dashboard Server (DS) product to deploy this application. Download the product from this git repository and build it by running `mvn clean install` command at the root POM. Once the build finishes, navigate to `modules/distribution/target` directory and extract the zip file to a preferred location. To run the server, use `./wso2server.sh` command inside the bin folder of the product at the location to which it was extracted earlier.
Note: You can skip tests when building the product using the command `mvn clean install -Dmaven.test.skip=true`
To support caramel in WSO2 DS, create a folder called caramel in the server’s modules directory. Then download the scripts and the `module.xml` from this git repository and include in that folder before starting the server.
Let’s get started!
First create folder named hello to contain the application code. Then, inside that folder, include the configuration of the application in a file called app.js as below.
This file specifies path parameters of the application, the theme and other configuration.
Notice that I’m declaring the variable caramel and initializing it in this file. Once you do so, you will be able to access methods of the caramel object as it will be treated as a global variable. The theme for this particular application will be named ‘classic’, the content of which will be created later in this post. If the theme we specify is not included in the project, it will render the pages according to a default theme.
Next, to initialize project’s app.js file include the following code in a file called jaggery.conf inside the hello folder.
Now let’s create the main controller of the application called index.jag. What is meant by ‘main controller’ is that this page will be invoked by a request, which is a result of a URL being hit by the browser. The main controller needs to define what data needs to be presented to serve the request.
Here, you will see that we have passed some data in to the render( ) method of the caramel variable declared earlier in app.js. It should noted that by using Caramel we can support multiple themes in our application and switch between them dynamically based on the request. So all you have to do is pass whatever the data that need to be rendered inside the caramel.render( ) method. After that, Caramel will take care of rendering those data according to whichever the theme configured. The theme has complete control over what user sees or receives for the request. It may be to display the data as simply JSON, or it may be to generate HTML from the data. A templating language such as handlebars helps you define the theme. In Caramel core, a handlebars theme engine is present to make things easier.
Now to handle theming of our application, first create a folder called themes inside the hello folder. As the app.js file states, the theme for this application is ‘classic’. To contain scripts related to this particular theme create a folder called classic inside the themes folder. To set the default theme engine for our application create a file called theme.js inside the classic folder to include the following.
To prepare the handlebars templates that define the view of our application, create a folder called pages inside the classic directory. In here, create a file called simple.hbs to include below code.
In Caramel, you will often come across the term Partials. A Partial is a generic piece of html that can be plugged in to a main html content. For example; we can create partials for sections like headers, footers and navigation bars. In the above code, I have plugged in two Partials called title and body. We will have to define these inside a new folder called partials created inside the classic directory and include the files title.hbs and body.hbs below.
Now that we have defined the components that will be rendered, it is time to define the renderer. Earlier, we noticed the caramel.render( ) function being called in index.jag. To define this render function thus called create a folder renderers inside the classic directory and include the code below in a file called index.js.
The page layout defined earlier under themes/classic/pages/simple.hbs is being called in the render function. Also above code defines from which partial to be selected and the data has to be rendered from it.
Now we are done with the application. Make sure your final application now has the directory structure below before testing.
Now go to https://localhost:9443/hello URL to view the application and you should see the output shown below.
