Introduction
In this post I’m presenting a boilerplate for Red Hat Mobile hybrid apps that can help developers getting started with Red Hat Mobile. This boilerplate contains web user interface components together with Red Hat Mobile framework components such as sync and push notifications and is based on the AngularJS Material framework and Apache Cordova for building responsive apps both for Android and iOS.
User interface
Several modules are provided that can be combined to create different user interfaces based on a common set of reusable components. For example a list with a side menu and a toolbar or a card layout with an analytics panel. There are three main view components: List, Form and Card. These can be combined with one, two or three of the utility modules: Sidenav, Toolbar and Analytics. For example you can build an app with a Form as main view, adding the Sidenav which provides additional functionality and the Toolbar that consists of a heading and a menu button. The Sidenav and Toolbar can then be reused in a second main view that might consist of the Card component and also adding the Analytics component. In total, this boilerplate makes it possible to create 3*8 different user interfaces – three main view components that each can use from zero to three different utility components.
To make it easier to see the structure of the user interface components, each component is attributed with a class with a different border color to the different modules as follows:
Red: Main view Dark Green: Toolbar Green: Sidenav Magenta: Analytics Yellow: Card, List, Form - Main view components which are mutually exclusive.
To remove the borders simply change the border-style from solid to none in styles.css.
The different components can be shown or hidden by changing a corresponding scope variable in view.controller.js. This simplifies locating problems in the layout.
View layout
The layout framework in AngularJS Material is based on rows and columns and the layout attribute is applied to the parent container.
For example div layout="row" will make all child elements align in a row. In addition there are several alignment attributes that are applied to the parent container and will affect the child elements, for example layout-fill that makes the child elements fills the horizontal size of the parent and layout-wrap that places children on a new row when the first row is filled.
The View component is the parent component of the other components. It has a column layout with the layout-fill attribute which makes its child elements horizontally fill the space created by the parent. In all below pictures, the red colored borders show the area occupied by the View component.
The topmost element in the View component consists of two immediate children: one for the toolbar and one for the remaining
elements. Both children contain the flex attribute.
The flex attribute is applied to the child elements to make them stretch horizontally in the space created by the parent. Aligning elements in a row depends on this when the width of the display changes which makes the user interface responsive to different screen sizes.
The component containing the remaining components (Sidenav, Analytics, List, Form and Card) has a row layout for screen sizes larger than 1280px. This is since the Sidenav stays open at that size and another component need to be able to sit to the right of it.
The green colored borders shows the area occupied by the Sidenav component while the magenta colored borders shows the area occupied by the Analytics component.
Modules
The modules can be added independently to the Main View in order to create multiple views by combining a main module with different utility modules. The main modules are Card, List and Form that constitutes the main area of the view.
These are mutually exclusive in a single view, however a multi-view app can be created by simply replicating the modules into additional AngularJS app modules.
The Toolbar, Analytics and Sidenav are reusable components that can be included in all three different main views.
Toolbar
The toolbar component has a row layout and consists of a md-toolbar directive and an image where a company logo can be placed.
The dark green colored borders shows the area occupied by the Toolbar component.
For screen sizes of 600px the layout changes to column using the layout-xs="column" attribute in the parent container.
Sidenav
The Sidenav consists of the md-sidenav directive and stays open at screen sizes larger than 1280px.
The Sidenav changes into a Toolbar with a menu on smaller screen sizes.
Analytics
The analytics component is based on the md-whiteframe directive. It consists of a canvas where a pie chart is drawn using statistical data provided by the application as input. The three different pie charts on the analytics panel can be used to display various analytics data as provided by the application or gathereed from back end systems. The text area elements within the panel contains the flex attribute in order for them to fill all space to the right of the canvas which in turn has a fixed size.
At screen widths of 600px or less the canvas size is reduced to 40% and the text elements are hidden behind an icon.
Card
The Card component uses the md-card directive and it’s parent uses layout="row" and layout-wrap to make the cards fill the parent space and create a new row when the first row is filled. The card elements have flex="none" to avoid shrinking or growing the cards when the width of the screen changes, instead cards are moved to new rows as needed. At screen sizes less than 600px the row layout changes into column.
The yellow colored borders shows the area occupied by the Card component and its sub-components.
List
The list component uses the md-list directive with to fit three lines of text in each row.
The yellow colored borders shows the area occupied by the List component and its sub-components.
Form
The form uses a row layout to provide input fields. It also provides a simple md-autocomplete implementation.
For screen sizes below 600px the row layout changes to column.
The yellow colored borders shows the area occupied by the List component and its sub-components.
Full UI
The full UI looks as follows on screens larger than 1280px:
and in xs:
with a list:
or with a form:
Boilerplate running on iPad after removing the borders:
Boilerplate running on iPhone after removing the borders:
Push module
The Red Hat Mobile Push Notification service allows mobile applications to send and receive push notifications regardless of whether the native OS is Android, iOS or Windows. This makes it ideal for including push notifications in hybrid apps built with for example Cordova. The boilerplate is used to include the $fh.push API into a Cordova/AngularJS app which will register the app with Red Hat Mobile’s built in Unified Push Notification Service.
The push initialization is located in the push module under public/js/push and consists
of a controller without a view that will register the device for Red Hat Mobile’s push notification service.
Note that in order to use push notifications the following additions must be made to the
boilerplate:
m-boilerplate/public directory to the www directory in the Cordova app project.
aerogear-cordova-pushplugin with cordova plugin add aerogear-cordova-push. See Aerogear for Cordova
Sync module
The sync framework built in to Red Hat Mobile allows mobile apps to subscribe to changes in persistent data and also publish changes made locally on the device. This makes ideal for mobile apps that sometimes will operate without connection to a network. The boilerplate is used to include the $fh.sync API into an AngularJS app.
The sync initialization is located in the sync module under public/js/sync and consists
of a controller without a view that will register the app for using Red Hat MAP’s sync service.
For demo purposes, the sync controller will create an initial document in the MongoDB collection that is being managed by the sync framework:
In a real application it will likely be one of the user interface controllers that will create and store new documents managed by the sync framework.
The sync data can then be included and displayed in other modules by using a service to store the data and $rootScope.$broadcast to announce that new data has arrived. Controllers subscribing to changes in the data injects the service to be able to retrieve the data and then use $scope.$on to listen for broadcasts from the rootScope and $scope.$apply to update the view accordingly. For example the List Controller:
angular
.module('list')
.controller('listController', ['$scope', 'syncService', function ($scope, syncService){
$scope.items = [];
// Subscribe to new data returned from the sync service
$scope.$on('sync', function (event, data) {
$scope.items = syncService.getData();
$scope.$apply();
});
...
}]);
The Sync Service:
angular
.module('sync', ['ui.router','ngFeedHenry'])
.service('syncService', ['FHCloud',
function(FHCloud) {
var service = {};
service.m_data = [];
service.putData = function(data) {
service.m_data = data;
}
service.getData = function() {
return service.m_data;
}
return service;
}]);
The Sync Controller:
// Make data available to other controllers
syncService.putData(data);
// Announce new data is available to other controllers
$rootScope.$broadcast('sync');
By using the broadcast mechanism in AngularJS all controllers can subscribe to sync events and update their views accordingly.
Deploying on Red Hat Mobile
To deploy the boilerplate on Red Hat MAP do the following steps:
1. In App Studio go to Projects then choose Import. 2. Create New Project 3. Select Empty Project 4. Select App Type = Cloud App 5. Import the boilerplate from a public git repo and use this link 6. Create a connection tag which requires a Client App. Simply go to Projects and create a Hello World App in the project. 7. Go to Connections and create a new Connection 8. Select Configure and copy everything in the JSON object into the file fhconfig which is located under md-boilerplate/public. 9. Deploy the Cloud App 10. Use the link to the Cloud App to access the mobile app
Summary
By using the Red Hat Mobile boilerplate for hybrid apps responsive user interfaces can be created more easily by combining component to provide different user interfaces for one or more apps. In addition Red Hat Mobile’s push and sync frameworks are included as modules which makes it easy to use push notifications and offline/online capabilities in Cordova apps. This provides a good starting point for quickly getting started developing hybrid mobile apps on Red Hat Mobile.
Credits
To Brid Mackay at Red Hat Mobile Consulting who provided lots of input to the creation of this boilerplate.