Giles Alexander edited this page Oct 18, 2012 · 5 revisions


Pages are the corner-stone of the cross-platform UI of Calatrava apps. The kernel of your app uses page references which Calatrava bridges to the native page implementations you provide. When implementing a Calatrava app you need to use the interface provided by a page reference in your cross-platform logic, and also implement the native pages according to the Calatrava pattern.

Page References

To get a page reference call calatrava.bridge.pages.pageNamed(), passing in the name of the page as a string. The page name will be a single word, camel-cased. The object returned provides a simple interface.

  • get(<fieldName>, <callback>): Reads a value from a field on the page, and then passes that value to the provided callback function. Requires a native implementation.

  • getMany(<fieldNameArray>, <callback>): Reads the values from each of the fields named in the array and then passes a single hash with all those values to the callback. The keys to the hash will be the names of the fields.

  • render(<viewMessage>): Updates the UI of the page to match the data in the passed viewMessage object. This is like a view model, but instead of a simple hash of data, it will typically contain top-level keys that affect which parts of the page are to be re-drawn. The native implementation of render is the most complex part of any page. Requires a native implementation.

  • bind(<event>, <callback>): Attaches a callback to a single event. The event is just a string. As events are bound at the page level, these will not be events like 'click' and will instead be more semantic, like 'search'.

  • bindAll(<bindings>): Attaches many callbacks to events. Each key is the name of the event, and the value at that key is the callback for the event.

Only the get and render functions correspond to functions that you have to implement for your native pages. However, these aren't the only functions you need to implement.

Mobile Web & Shell Page Implementations

For Mobile Web apps, and the shell shared across all apps, pages are implemented in two parts: there is a fragment of Haml providing the markup and a CoffeeScript function that returns an object containing five known functions. There are some naming rules that must be followed.

  • The CoffeeScript function must be stored in the hash calatrava.pageView. The hash key must be the page name.

  • The Haml fragment must be a div. The class of the div must be page and the id of the div must be the page name.

The CoffeeScript function should return an object that contains the following methods.

  • get(<fieldName>): Return the value of the named field. Typically, you would use Zepto to query the DOM for the appropriate value.

  • render(<viewMessage>): Update the UI of the page according to what is in the viewMessage. Typically, you would use an ICanHaz.js template.

  • bind(<event>, <handler>): This directly corresponds to the bind method from a page reference. The implementation for this function typically maps from a semantic event, like 'search', to a physical event, like 'clicked the button with id search'.

  • show(): Show the page, typically by unhiding the div.

  • hide(): Hide the page, typically by hiding the div.

The two files containing these implementations must be placed in the feature directory under shell/pages.

Using the shell as the UI in your iOS or Android app requires some specific things be done. This is described on the Shell page.

iOS Page Implementations

For iOS page implementations, create a new class that inherits from BaseUIViewController. This new class must be named <PageName>ViewController. The class should implement the following methods.

  • valueForField:(NSString *)field: Used by the get method of the page reference to read a field value. Returns the value.

  • render:(NSDictionary *)viewMessage: Used by the render method of the page reference.

When implementing your iOS view controller you will typically be binding to events raised by iOS native widgets. to get these events back to the kernel, use the method dispatchEvent:(NSString *)eventName withArgs:(NSArray *)args provided by the base class.

Android Page Implementations

For Android page implementations, create a new class that inherits from com.calatrava.bridge.RegisteredActivity. This new class must be tagged with the CalatravaPage annotation, including the name attribute set to the page name. The class should implement the following methods.

  • String getFieldValue(String field): Used by the get method of the page reference to read a field value. Returns the value.

  • void render(final String json): Used by the render method of the page reference.

Again, your Android activity must raise semantic events back to the kernel. To do this, use the method com.calatrava.bridge.RegisteredActivity.triggerEvent(String event, String... extraArgs).