View source | Discuss this page | Page history | Printable version   

Mobile Common Components

Contents

Introduction

Each component is a piece of UI that can be used together with other components to build a whole window. Components are defined using enyo that wraps the HTML DOM.

Following enyo's approach, a component can be composed by nested components. When designing new components, this should be kept in mind in order to create smaller components that could be reused.

Openbravo Mobile Core provides a palette of common components that can be reused to create your own ones. The aim of this document is to present some of them, explaining how they can be adapted to be used in different places.

Layout

The components explained in this section are used to compose the layout of the application.

Mobile-layout.png

Terminal

It is the holder where the rest of windows are rendered in.

Detailed information can be found in its main article.

Window

Windows are components that are rendered in the terminal, they can be navigated from the menu or opened programmatically.

Further information can be found in its main article.

Multi Column Layout

The standard layout for mobile windows consists in two columns designed to properly work in different mobile devices. But this is optional. You can create your own window component.

As shown in the image above, the standard layout is two column. But, if the device width is not wide enought (less than 800px), the layout auto-switches to single column (image below).

Mobile-layout-columns.png

Each of these two columns are composed by a Toolbar at the top and a Panel. The Toolbar holds the buttons and the Panel holds the contents. In single column mode, a Column switcher button is automatically added to the toolbar, this button allows the user to navigate from one column to the other (it is also possible to swipe between columns).

If you want a window to support this layout, OB.UI.MultiColumn must be its main component:

 
enyo.kind({
  name: 'OB.MYMODMyWindow.UI.MyWindow',
  kind: 'OB.UI.WindowView',
  windowmodel: 'OB.MYMODMyWindow.Model.MyWindow',
  components: [{
    kind: 'OB.UI.MultiColumn',
    name: 'multiColumn',
    leftToolbar: {
      kind: 'OB.MYMODMyWindow.LeftToolbar'
    },
    leftPanel: {
      kind: 'OB.MYMODMyWindow.LeftPanel'
    },
    rightToolbar: {
      kind: 'OB.MYMODMyWindow.RightToolbar'
    },
    rightPanel: {
      kind: 'OB.MYMODMyWindow.RightPanel'
    }
  }],
  init: function(model) {
    ...
  }
});

OB.UI.MultiColumn kind expects the following attributes:

Bulbgraph.png   It is possible not to define rightToolbar and rightPanel. If so, only the left column will be displayed. The switch button will never be shown in the window. This makes special sense for simple windows designed to be mainly used in small mobile devices.

Toolbar

Mobile-toolbar.png
 
enyo.kind({
  name: 'OB.MYMODMyWindow.LeftToolbar',
  kind: 'OB.UI.MultiColumn.Toolbar',
 
  showMenu: true,
 
  buttons: [{
    kind: 'OB.MYMODMyWindow.ButtonNew',
    span: 3
  }, {
    kind: 'OB.MYMODMyWindow.Button2',
    span: 3
  }, {
    kind: 'OB.MYMODMyWindow.Button3',
    span: 6
  }]
});

OB.UI.MultiColumn.Toolbar is the component that is used to represent the toolbar in a multicolumn layout.

It has 3 kind of buttons:


Toolbar Custom Buttons

E.g.: the new button

POS-toolbarButton.png
 
enyo.kind({
  name: 'OB.MYMODMyWindow.ButtonNew',
  kind: 'OB.UI.ToolbarButton',
  icon: 'btn-icon btn-icon-new',
 
  events: {
   onNewDocument: ''
  },
 
  tap: function () {
    this.setDisabled(true);
    this.doNewDocument();
  }
});

Toolbar custom buttons are placed inside a toolbar, they are OB.UI.ToolbarButton kind (extend from).

Buttons can be disabled/enabled using their setDisabled method.


Empty Toolbar

Empty-toolbar.png

Some windows won't require any button. But, even in this cases, the toolbar is still needed to show the menu button as well as the column switcher. OB.UI.MultiColumn.EmptyToolbar is a convenience kind to do it:

 
enyo.kind({
  name: 'OB.MYMODMyWindow.MyEmptyToolbar',
  kind: 'OB.UI.MultiColumn.Toolbar',
 
  showMenu: true,
 
  buttons: [{
   kind: 'OB.UI.MultiColumn.EmptyToolbar',
   i18nLabel: 'MYMODMyWindow_ToolbarTitle'
  }]
});

This component displays a toolbar with a title. The toolbar title is defined in the i18nLabel and points to the localizable Search Key labeled MYMODMyWindow_ToolbarTitle that must have been added within the backend.

Menu

Mobile-menu.png

Windows in mobile applications can display a standard menu.

Menu is configured at toolbar level. To make the menu button available, showMenu option must be set to true.

Menu is composed by different types of options:

Adding custom menu entries

 
enyo.kind({
  kind: 'OB.UI.MultiColumn.Toolbar',
 
  showMenu: true,        // makes the menu available
  showWindowsMenu: true, // shows entries for standard windows
  // menuEntries defines custom entries
  menuEntries: [{
    kind: 'OB.UI.MenuAction',
    i18nLabel: 'MYMOD_EntryName1',
    eventName: 'onMyAction1',
    permission: 'MYMOD_Action1Permission',
  },
  {kind: 'OB.UI.MenuSeparator'},
  {
    kind: 'OB.UI.MenuAction',
    i18nLabel: 'MYMOD_EntryName2',
    eventName: 'onMyAction2',
  }],
  ...
});

Custom menu entries are defined by the menuEntries toolbar property. It is an array of OB.UI.MenuAction kinds. These are the properties:

Bulbgraph.png   It is possible to add a separator, rendered as a gray line, between two entries by adding a OB.UI.MenuSeparator kind in between them.

Keyboard

POS-keyboard.png
 
enyo.kind({
  kind: 'OB.UI.Keyboard',
  sideBarEnabled: true,
  initComponents: function() {
    // initialize keyboard with needed customizations
  }
});

Keyboard is the main component to allow user data input.

Keyboard components extend OB.UI.Keyboard enyo kind. A keyboard is composed by 3 elements: toolbar, keypad and sidebar. These elements can be customized when defining a new keyboard.

Keyboard's Toolbar

The very left column of buttons, is the toolbar (see image above). Each of the buttons in the toolbar represents a different command. For the user, there are two ways of executing these commands:

It is possible to add a new toolbar to a keyboard. Check this sample below (Note that the code goes inside the initComponents method of the keyboard):

 
initComponents: function() {
  ...
 
  this.addToolbar({
    name: 'myToolbar',
    buttons: [{
      command: 'myCommand',
      label: OB.I18N.getLabel('OBPOS_KbCode'),
      classButtonActive: 'btnactive-blue',
      definition: {
        action: function(keyboard, txt) {
          // implement logic here
        }
      }
     }
     // additional buttons can be added in this array
    ],
    shown: function() {
      var keyboard = this.owner.owner;
      keyboard.showKeypad('basic');
      keyboard.showSidepad('sideenabled');
      keyboard.defaultcommand = 'myCommand';
   });
  ...
}

The addToolbar method receives a plain javascript object, let's see the properties it has:

Bulbgraph.png   addToolbar method allows to add standard toolbars. It is also possible to add more complex toolbars (i.e. with a different button arrangement) using the addToolbarComponent method which receives an enyo kind to be rendered as toolbar.

Keypad

It is the central set of keys that enables the user to add information (see image above). By default, there's a numeric keypad, but it is possible to define custom ones. A keyboard can have multiple keypads being possible to switch between them regarding some action.

A new keypad can be created as an enyo component and added to the keyboard using the keyboard's addKeypad method. New keypad components need to have a padName property that is used to show it using showKeypad method in the keyboard. By default, all keyboards have a numeric keypad named basic.

Sidebar

Currently the buttons displayed in the side bar are not customizable. There are two out of the box sidebars:

Implementing commands

Commands can be implemented in keyboard's initComponents method. Note that this should be done before invoking the parent's constructor this.inherited(arguments).

 
  initComponents: function() {
    ...
 
    this.addCommand('line:price', {
      permission: 'OBPOS_order.changePrice',
      action: function(keyboard, txt) {
        if (keyboard.line) {
          keyboard.receipt.setPrice(keyboard.line, OB.I18N.parseNumber(txt));
          keyboard.receipt.trigger('scan');
        }
      }
    });
    
    ...
    this.inherited(arguments);
  }

Commands are added to the toolbar with the addCommand method. It receives two arguments:

Confirmation popups

Mobile-popup.png

Confirmation popups are modal popups displaying a message and a set of buttons. They are shown by invoking the OB.UTIL.showConfirmation.display(title, msgText, buttons, options) method.

 
OB.UTIL.showConfirmation.display(
    // title
    OB.I18N.getLabel('OBWH_DeleteDocumentTitle'),
    // msgText
    OB.I18N.getLabel('OBWH_DeleteDocumentText'),
    // buttons
    [{
      label: OB.I18N.getLabel('OBWH_DeleteLbl'),
      action: function () {
        me.setDisabled(true);
        me.bubble('onDeleteDocument');
      }
    }, {
      label: OB.I18N.getLabel('OBMOBC_LblCancel')
    }],
    // options
    {
      onShowFunction: function (popup) {
        //executed when the popup is opened
      },
      onHideFunction: function (popup) {
        //something to do when the popup
        //is closed without use an action
      },
      style: 'background-color: #EBA001'
    }
);

Parameters in detail:

If defined, this function will be executed when the popup is hidden without executing actions. It means that this function will be executed using the background, the close (x) button or a button which doesn't defines an action.

Complex modal windows

Mobile-Modal-window.png

When confirmation poupups are not enough, it is possible to define modal popups with any arbitrary content.

 
enyo.kind({
  name: 'OBWH.Movement.ProductSearch',
  kind: 'OB.UI.Modal',
 
  i18nHeader: 'OBWH_Product',
  body: {
    kind: 'OBWH.Movement.ProductSearchList',
  }
});

The kind implementing the modal window extends OB.UI.Modal, the properties it defines are:

This code should be to add a popup to a window:

 
enyo.kind({
  name: 'OBWH.Movement.View',
  kind: 'OB.UI.WindowView',
  windowmodel: OBWH.Movement.Model,
 
  components: [{
    kind: 'OB.UI.MultiColumn',
    ...
  }, {
    kind: 'OBWH.Movement.ProductSearch',
    name: 'modalProductSearch'
  }]
});

It is important to name this popup because that name will be used to identify that popup in the open and close events.


Showing a popup

To show a popup, the event doShowPopup must be thrown. This event will receive two parameters:

  1. the name of the popup that we want to show.
  2. args to be received by the executeOnShow function of the affected popup
 
this.doShowPopup({
  popup: 'mymodalname'
});
//Args can be added to the event. This args will be saved in the popup component. This args can be read from the popup component using "this.args".
//The function executeOnHide of the popup will be executed.
this.doShowPopup({
  popup: 'mymodalname',
  args: myParameters
});

Hiding a popup

From inside

To hide a popup from a button that is inside the popup, the event doHideThisPopUp must be thrown, and the current popup will be hiden.

 
this.doHideThisPopup();
//Args can be added to the event. This args will be saved in the popup component. This args can be read from the popup component using "this.args".
//The function executeOnHide of the popup will be executed.
this.doHideThisPopup({args: myParameters});

From another component

To hide a popup from other component, the event doHidePopup must be thrown. This event will receive two parameters: 1. the name of the popup that we want to hide 2. args to be received by the executeOnHide function of the affected popup

 
this.doHidePopup({
  popup: 'mymodalname'
});
//Args can be added to the event. These args will be saved in the popup component. These args can be read from the popup component using "this.args".
//The function executeOnHide of the popup will be executed.
this.doHidePopup({
  popup: 'mymodalname',
  args: myParameters
});

Adding a popup from other module

How to create a new modal from a module

Retrieved from "http://wiki.openbravo.com/wiki/Mobile_Common_Components"

This page has been accessed 10,046 times. This page was last modified on 23 April 2013, at 11:55. Content is available under Creative Commons Attribution-ShareAlike 2.5 Spain License.