Mobile Windows

Contents 1 Introduction 2 Main Layout 3 Window definition 3.1 View 3.1.1 Two Column Layout 3.2 Window Model 4 Registering a window

Introduction

The main UI component in Openbravo Mobile are windows. Generally, each window represents a different functional flow. It, optionally, can be opened from the main menu.

A window is composed by a model containing the data and business logic and a view representing it in the UI.

Main Layout

Layout of Mobile Applications consists on:

• Terminal: is the container of the whole application. It provides some basic infrastructure and it is where the rest of the windows are rendered.
• Window: is the object this article describes. Rendered within the terminal and opened using the main menu.

Window definition

A window is composed by two main parts, view and model. They are explained in the sections below.

View

A window view is the UI representation (enyo kind) of the window's data model (Backbone model). The view should take care of the representation whereas all the business logic should be implemented by its associated window model.

The source would look similar to this snippet:

 
enyo.kind({
  name: 'OB.MYMODMyWindow.UI.MyWindow',
  kind: 'OB.UI.WindowView',
  windowmodel: OB.MYMODMyWindow.Model.MyWindow,
  components: [...],
 
  init: function(model) {
    ...
  }
});

• name, it is the name of the javascript class defining the window enyo kind. In order to avoid possible conflicts with windows defined by other modules, it should be placed inside the OB object in another object starting with the DB Prefix of the module providing the window
• kind, all windows must extend OB.UI.WindowView enyo kind. This kind provides the proper initialization for the window, including loading of the window model and invocation of init method after this is accomplished
• windowmodel, is the javascript class that implements the model (data and business logic) for the window. When the window is opened, a new instance of this model is created in the model property of the window. Model is deeply explained in the following section
• components, it is the collection of the UI components that will render the whole window. These components (enyo kinds), can be own implemented or reused from the common ones provided out of the box
• init method is executed whenever the window is opened, just after loading all the online models defined within its window model. It receives as parameter the window model that uses this view. Note that the init method is invoked in all of the subcomponents the view might have, making the model accessible at any level. Using the received model in the view should be done cautiously as it is recommended to implement all business logic in the model and not in the view

Two Column Layout

Standard layout for mobile windows consists in two columns. Note that this is optional. You can create your window as a component in the way it better fits your needs, but this default layout is designed to properly work in different mobile devices.

More detailed information on how to support this layout can be found here.

Window Model

Each window has a model, this model is in charge of loading the data required by the window and of implementing the client side business logic of the window.

A window model is a javascript class extending OB.Model.WindowModel, which is a Backbone model.

 
OB.MYMODMyWindow.Model.MyWindow = OB.Model.WindowModel.extend({
  models: [...],
  init: function() {
    ...
  }
});

Usually, a window model contains a collection of data models as an array of model classes in the models property. When the window is opened, all the online data models are loaded and the init method is invoked afterwards. A window needs at least one model to initialize.

Data loaded in these models can be accessed using the getData method. This method receives as parameter the modelName of the data model and returns the Backbone collection with the loaded data.

Data for models can be loaded from the backend at two different moments, regarding on the model type:

• offline. Data for these models is stored in browser's local database and it is always used from there. These models are refreshed when user logs, being online, into the application; in case user logs in being offline, local data is not refreshed using what already was in local DB.
• online. Data is loaded whenever the window is opened (using the OB.MobileApp.model.navigate method).

More information about how to define data models can be found here.

Registering a window

To make the window accessible and navigable, it is necessary to register it in this way:

 
OB.MobileApp.windowRegistry.registerWindow({
  windowClass: OB.MYMODMyWindow.UI.MyWindow,
  route: 'mymod.myWindow',
  menuPosition: 100,
  menuI18nLabel: 'MYMOD_LblMyWindow',
  permission: 'MYMOD_PermissionPreference'
});

• windowClass: is the javascript class that defines the window
• route: is the string that the OB.MobileApp.model.navigate method will use to locate and load the window. E.g.: OB.MobileApp.model.navigate('mymod.myWindow');
• menuPosition (optional): if specified, defines the position of the menu entry in the main menu
• menuI18nLabel (optional): when the window is part of the main menu, this property defines the text for the menu entry. This is a localizable label that must be defined in the Messages category of the backend
• permission (optional): is the permission preference that grants access to this window. See Security Model for more information

Category: Mobile Developers Guide