Tutorial

The following tutorial gives a short introduction into the Ben.JS framework. This tutorial should only take 5 minutes if you are familiar with JavaScript and HTML. A general guideline explaining the concepts of Ben.JS can be found in the guidebook. Ben.JS provides also additional examples which can be checked out at the project home on Github.

So please fasten your seat belts and start the 5 minute tutorial!

Note This tutorial uses Ajax calls to load page fragments into the application. If you did not load your files form a web server this will result in a ‘Cross origin Exception’. To avoid this during developing the application locally you can start the chromium browser in a developer mode with the following command:

# Linux
chromium --allow-file-access-from-files
# Windows
chromium -allow-file-access-from-files

The Application Main Page

A single page application is, as the name suggests, an application consisting of only one page. The Main page (index.html) provides the layout and the business logic provided in an application specific JavaScript file (app.js). So the main page in Ben.JS can look like this:

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Ben.js - Tutorial</title>

<link href="../css/creatix-basic.css" rel="stylesheet" />
<link href="../css/creatix-forms.css" rel="stylesheet" />
<link href="../css/creatix-layout.css" rel="stylesheet" />
<link href="../css/custom.css" rel="stylesheet" />

</head>
<body>
    <div id="container">

       <h1>Ben.js - Tutorial</h1>
       <div data-ben-template="app-header"></div>
       <div data-ben-template="app-content"></div>

    </div>
    <script type="text/javascript" src="../lib/jquery-2.1.4.min.js"></script>
    <script type="text/javascript" src="../lib/ben.js"></script>
    <script type="text/javascript" src="app.js"></script>
</body>
</html>

The page loads the required css and JavaScript libraries and defines two template sections ‘app-header’ and ‘app-content’ in the page body. These sections are used to display application specific views.

The app.js

The business logic in this tutorial is placed into a library named ‘app.js’. This is sufficient for the tutorial. In an bigger project you can also split your application into several libraries. The app.js is used to define the model and controllers and starts our application:

var benJS=BENJS.org.benjs.core;

/** Model Definition **/
//.....

/** Controller Definition **/
//...

/** Template Definition **/
//......


/** configure benJS (optional) **/
benJS.init({
    appVersion : "1.0.0"
});

The Model Definition

First of all we need to define a model used by our application. To keep it simple this tutorial defines a simple ‘human resources management’. So we define two simple JavaScript objects: ‘Employee’ and ‘company’

function Employee(name, city, date) {
    this.name = name;
    this.city = city;
    this.date = date;
}

function Company() {
    this.employers = new Array();
    this.employers.push(new Employee('Anna', 'Munich', '19.7.2015'));
    this.employers.push(new Employee('Sam', 'Berlin', '20.7.2015'));
    this.employers.push(new Employee('Douglas', 'Hamburg', '21.7.2015'));
}

As you can see the Employee model object is quite simple and defines the attributes ‘name’, ‘city’ and ‘date’. The Company model object contains a list of employers. Ben.JS did not restrict you how to define you model objects. In most cases those models would be defined by a back-end Rest API used by your application.

The Controller definition

Next we define two controllers to bind our model objects into the view. This can be done with the following short code snippet:

var employerContrl = benJS.createController({
    id: "employee-controller", 
    model: new Employee()
});

var companyContrl = benJS.createController({
    id: "company-controller", 
    model: new Company()
});

The View

So far we have defined our model and we created two controllers. Now we can create a view. In Ben.JS is just a simple HTML snippet. We create a new HTML page ‘employers.html’ to display all employers of our company:

<div data-ben-controller="company-controller">
    <table>
       <thead>
         <tr>
          <th>Name</th>
          <th>City</th>
          <th>Date</th>
         </tr>
       </thead>
       <tbody data-ben-foreach="employers">
         <tr>
          <td data-ben-model="name">
          <td data-ben-model="city">
          <td data-ben-model="date">
         </tr>
       </tbody>
    </table>
    <p>
       <span data-ben-model="employers.length"></span> employers total
    </p>
</div>

The view template defines a controller section with a ‘data-ben-controller’ and a ‘data-foreach’ block to iterate over all employees from our data model. Ben.JS will automatically resolve the model objects and push the data into the ‘data-ben-model’ elements.

To load this view in the startup phase of our application we need to define a Template in our app.js which we haven’t done yet:

var contentTemplate = benJS.createTemplate({
    id: "app-content", 
    url: "employers.html"
});

This contentTemplae is associated with the template section ‘app-content’ in our index.html. The second parameter tells Ben.JS to load the emplyers.html page automatically during startup.

The result is a list of all employees in our company:

Image Alt

If you open the browser console you can see also the runtime-protocol printed by Ben.JS. This can be helpful to debug the application during development.

Image Console

Add Business Logic

So far Ben.JS did provide most of the business logic out of the box. We defined the employee and company model and Ben.JS displays all our employers in the employers.html page.

Next we want to add some business logic to manipulate our model object and add some new data. So let’s hire new employees!

Adding a Form

First of all we need a new view template to provide a Form. This can be done like in the following example:

 <div class="row">
    <div data-ben-controller="employee-controller">
       <h3>Form:</h3>
       <dl>
         <dt>Name</dt>
         <dd>
          <input type="text" data-ben-model="name" />
         </dd>
         <dt>City</dt>
         <dd>
          <input type="text" data-ben-model="city" />
         </dd>
         <dt>Date</dt>
         <dd>
          <input type="text" data-ben-model="date" />
         </dd>
       </dl>
       <input type="button" value="Save" onclick="employerContrl.save();"
         class="btn" />
    </div>
</div>

Defining a Route

As we now have defined a new Form we need a way to display the employee Form when the user clicks on the ‘add new’ button in the employers view. Here the concept of Routes come into the game. A Route defines a new application state and can be used to switch between different views. First we need to define a new Route in our app.js:

/** Router Definition **/
var employeeRoute = benJS.createRoute('employee-route', {
    "app-content" : "employee.html"
});

The new route defines the employee.html page to be loaded in our view template ‘app-content’. To initialize a new Employee model object we can add a callback method. All objects provided by Ben.JS provide callback methods to add additional business logic. We add a new function to the callback method ‘beforeRoute’ to add a new empty Employee model object.

employeeRoute.beforeRoute.add(function(f) {
    employerContrl.model=new Employee();
});

Now we can add an action button into the employers.html view to call the new route:

<input type="button" value="add new"
         onclick="employeeRoute.route()" class="btn" />

This action button will load the new app-content and also trigger our callback method which provides an empty Employee model object.

Add business logic into a controller

The final step we need is to add the new employee data object into the company model object when the user clicks on the save button of our form.

Image Console

There for we can either add another Router definition with a callback method or we can extend our employerContrl. In this example we extend the employerContrl to demonstrate the flexibility of the concepts provided by Ben.JS:

What we need to do when the user click on the save button of our form is to add the new employee data into the employers list and to show the updated view. This can be done with the following extension:

employerContrl.save = function(f) {
    // load the form data
    this.pull();
    // add the new employee data into the company model...
    companyContrl.model.employers.push(this.model);
    // load the emloyers view...
    contentTemplate.load("employers.html");
}

This example shows how a new function can be added into the controller instance provided by Ben.JS. With the method call ‘pull()’ the data entered into the form will be synchronized with our model object. Then we access the model object of the companyContrl to add the new employee data object. Finally we call the load() method of our contentTemplate to reload the view with our Employers data.

That’s it!

Conclusion

This short tutorial demonstrated the core concepts of Ben.JS.

  • By defining templates we can split up a single-page-application into separate parts.
  • The Ben.JS controller concept provides and easy way to bound a model object into a view.
  • Routers can be used to control the page flow and add business logic.
  • All objects provided by Ben.JS can be extended with additional functionality.

You will find more information about the concepts in the guidebook. If you have questions post them on Github.

Finally we invite you to join this project and share your ideas.