Creating your first hybrid application
This tutorial describes all the steps from creating a new MobileFirst project and application to building it. The tutorial explains the structure of the new project and all of its components, and the concept of "Single-Page Application" (SPA) that MobileFirst applications are based on. Finally, the tutorial shows how to preview the newly created application. This aspect will be covered in more detail in specific tutorials.
- Creating a new MobileFirst project and application
- The structure of the new application
- Single Page Application
- Sample application
Creating a hybrid MobileFirst application
- In MobileFirst Studio, select File > New > MobileFirst Project to create a new MobileFirst Project from the top toolbar:
- Give your project a name, for example HelloWorldProject, and select the Hybrid Application template:
To learn more about adding frameworks to applications, read the Client-side development basics > Working with UI frameworks tutorial.
Familiarizing with the application files and HTML structure
The default environment is called common. The common environment contains all of the resources that are shared between environments:
- index.html: main HTML file
- main.css: main application CSS file.
- images: Default MobileFirst images for the common environment
- initOptions.js: Contains initialization options for the application
- messages.js: A JSON object that holds all app messages. Can be used as the source for translation
- legal: A folder that holds all the legal docs
- application-descriptor.xml: Contains the application metadata
- build-settings.xml: Contains configuration options for minification and concatenation
To add an environment, right-click the apps folder and selecting New > MobileFirst environment, or use the top toolbar icon. The resources of the new environment have the following relationship with the common resources:
- images – Overrides the common images when both have the same name.
- css – Extends, overrides, or both, the common CSS files.
- js – Extends the common application instance JS object. The environment class extends the common app class.
- index.html – Optional HTML file that overrides the common HTML code when both have the same name.
- externalServerLibraries: Contains the libraries to be placed in external service servers and used for access token validation (by the service).
- server: Contains files that are used for server-side customization of a project:
- conf: contains
- authenticationConfig.xml: Defines authentication realm and security tests.
- default.keystore: A default SSL certificate that is provided by the project.
- login.html: Presents a login form for web environments and the MobileFirst Console./li>
- SMSConfig.xml: Defines SMS Gateways.
- worklight.properties: Defines the properties that are used by MobileFirst Server.
- java: Used to hold Java classes that will be compiled and deployed to a MobileFirst Server instance after the application is built. You can place your custom Java code here.
- lib: Used for JAR files that are deployed to the server.
- conf: contains
- services: Contains any back-end services that were discovered.
The bin folder
The bin folder contains project artifacts that are deployed to MobileFirst Server. MobileFirst Studio deploys those artifacts to the embedded MobileFirst Development Server automatically as a part of the build process.
- .wlapp files are application bundles.
- .wladapter files are adapters.
- .jar and .war files are server customization files that contain
authenticationConfig.xml, and custom Java code.
The Application Descriptor is an XML file that stores the metadata for an application. You can edit this file with the Design or Source editors.
The file is based on the W3C Widget Packaging and Configuration standard and contains application properties that are used at build time. You can specify the application description, details about the author, and the thumbnail image to be displayed in the MobileFirst Console.
Environment-specific information is inserted automatically as new environments are added to the MobileFirst project:
The Build Settings file is an XML file that contains configuration options for minification and concatenation of the Desktop Browser and Mobile Web environment web resources. This file can be edited with the Design or Source editors.
During application runtime, the main HTML document cannot be replaced by another HTML document. The default application HTML template complies with HTML5 standard markup, but any other DOCTYPE can be specified.
The MobileFirst client-side framework uses the jQuery library for internal functions. By default, the
$ char is assigned to the internal jQuery in the main HTML file (see below). If using a different jQuery version is required or if jQuery is not required in the application, this line (#12) can be removed.
The MobileFirst client framework initialization is bound to the
onload event specified in the
initOptions.js file. For more information about the initialization options, see the user documentation.
initOptions.js file contains MobileFirst framework initialization settings.
It is also responsible for initializing the MobileFirst framework once the
element finishes loading.
By default, the MobileFirst application starts in offline mode (the application does not attempt to connect to the MobileFirst Server).
To connect to the MobileFirst Server, use
Some default initialization options are documented in the file itself, with the entire set of options available in the MobileFirst Platform Foundation user documentation topic for the API method "
When creating an application, a
It contains a
wlCommonInit() function that is invoked automatically after the MobileFirst framework initialization finishes. Application initialization code can be implemented herein.
As discussed previously, the MobileFirst application starts in offline mode by default.
To begin communicating with MobileFirst Server, follow the instructions provided in the default
Building an application
To build an application, right-click the application name and select Run As > Run on MobileFirst Development Server.
While the application is being built and deployed, the progress can be monitored in the Eclipse Console view. After the build completes, the application is available for preview in the catalog tab of the MobileFirst Console.
To view the MobileFirst Console, right-click the project name and select Open MobileFirst Console. To view MobileFirst Console in an external browser window, from the top menu bar in Eclipse go to Window > Preferences > General > Web Browser and select the “Use external web browser” radio button.
To preview the application in its current form, click Preview as Common Resources.
Single DOM Model
MobileFirst hybrid applications use a single DOM model.
The single DOM model means that navigation between various HTML files must not be implemented by using hyperlinks or by changing the
Instead, a multipage interface can be implemented by loading an external HTML file content by using Ajax requests and injecting it into an existing DOM.
This module explains the principles of a single-page application. Principles of multipage applications that are built with a single DOM model are explained in other tutorials.
Click to download the sample application for this tutorial.▲