jonny edited this page Oct 23, 2012 · 2 revisions


Calatrava is an opinionated framework. It isn't designed to be a general way of calling native code from JavaScript. Instead, it's designed to support developing applications using a particular structure. We think this design is actually a pretty good one for many mobile apps.

A Calatrava app is broken down into features. These features are driven by one or more controllers. Each feature has a start function and a set of pages.

From your Calatrava app you can build an iOS app, an Android app and a Mobile Web app. The shared controlling logic is called the kernel. If you are building a shared HTML UI, that is called the shell.

Connecting your kernel code to the UI of your app and any native device features you are using is the bridge. This is the main piece that the Calatrava framework provides.


A feature is a directory of CoffeeScript files under the directory kernel/app. Any shared HTML UI is placed in Haml and CoffeeScript files in a directory with the same name under shell/pages. In the Calatrava sample app, there is a single feature called converter.

A feature typically has a start function. This will get references to pages from the bridge, and pass these to the controllers of the features.

To get a reference to a page call calatrava.bridge.pages.pageNamed() and pass the name of the page, as a string. See Pages for more details on how to define pages.


The pages are the cornerstone of a cross-platform Calatrava app. Each page is a logical screen or page in your app. The kernel of your app interacts with references to these pages. On each platform, Calatrava will bridge from this reference to the actual page implementation.

  • On iOS, each page is a view controller.
  • On Android, each page is an activity.
  • On Mobile Web, each page is chunk of Haml and a JavaScript object. The Haml becomes a div embedded within the single-page of the app.

Each controller of your app will bind to events raised by pages, extract data from the page and render new data to be displayed on a page. To take your user through your app, controllers will change between different pages using calatrava.bridge.changePage(), passing the target page name as a string.

Page implementations are not cross-platform, by design. Logic in here should be kept to a minimum and should generally only deal with rendering view models.

See Pages for more details.


The kernel is where the cross-platform logic of your app is implemented. This is written in CoffeeScript and divided up into features. The only way for any code in the kernel to affect the UI is to call a page reference.


When building Calatrava apps, we've found that often an HTML UI can be sufficient for many parts of the app. This shared HTML UI is implemented in the shell. The shell is divided up into features to match the kernel. Each feature contains pairs of Haml and CoffeeScript to implement the page objects.

We recommend that you start by building all UIs in HTML, and only switching to native when necessary. There are three advantages.

  1. Automated acceptance testing of the app is very easy using a web UI running in a browser.

  2. You build a Mobile Web app for free.

  3. Iterating over interaction design tends to be faster using web technologies. You can replace with native once the design is validated.


The bridge is the core of Calatrava. This is a set of functions and objects, used from both your cross-platform logic and your native UIs. For more information, see the Bridge API.