Getting Started with Oracle JET Hybrid Mobile Application Development

The Oracle JavaScript Extension Toolkit (JET) framework includes support for hybrid mobile application development, providing Android and iOS Alta themes and UI behavior on Oracle JET components, starter applications, design patterns, and tooling support.

Before you can create your first hybrid mobile application, you should become familiar with the Oracle JET mobile features and third-party technologies. You must also install the prerequisite packages and Oracle JET mobile tools.

Tip:

If you’re strictly interested in developing web applications that run in desktop and mobile browsers, you don’t need to install the mobile tooling framework. For information on developing web applications, see Getting Started with Oracle JET Web Application Development

Installing the Mobile Tooling

Before you can start creating Oracle JET hybrid mobile applications, you must install Cordova on your development machine. To develop hybrid mobile applications for iOS and Android, you must also install the Android and iOS development tools.

To install the mobile tooling:
  1. If needed, install the tooling prerequisites as described in Install the Prerequisite Packages
  2. Install Cordova
  3. (Optional) Install Android Tools
  4. (Optional) Install iOS Tools

Install Cordova

Install Cordova on your development machine.

As Administrator on Windows or using sudo on Macintosh and Linux systems, enter the following command to install Apache Cordova:

[sudo] npm install -g cordova

Install Android Tools

To develop applications for the Android platform, you must install the Android Software Development Kit (SDK) and create Android Virtual Devices (AVDs) representative of your application’s target devices that you can run in the Android emulator. You must also enable remote debugging if you want to test your application on an attached Android device.

  1. Using Cordova’s Android Platform Guide, install the Android tools on your development machine.

    As part of the installation process, you will see an option to install Android Studio which includes an IDE in addition to the SDK tools. You do not need to download the Studio version to work with the Oracle JET mobile tooling. However, Android Studio adds an integrated IDE that you can use for any Android development project and to create your own Cordova plugins.

  2. If not done already, enable remote debugging on attached Android devices following the instructions at: https://developer.chrome.com/devtools/docs/remote-debugging.

Install iOS Tools

To develop applications for the iOS platform, you must install the iOS development environment and iOS Simulator which is only available for Intel-based Macs.

Using Cordova’s iOS Platform Guide, install Xcode and the iOS Simulator on your development machine.

Note:

This step is sufficient for developing iOS applications and testing on iOS simulators. If, however, you want to use an actual iOS device for testing or deploy your application to the Apple App Store, you must create a provisioning profile and join the Apple iOS Developer Program. For additional information, see the platform guide. For details about using the Oracle JET tooling to package and deploy your hybrid mobile application, see Packaging and Publishing Hybrid Mobile Applications.

Creating a Hybrid Mobile Application

You can use the Oracle JET mobile tooling commands to create, build, and run the hybrid mobile applications for iOS and Android mobile devices. You can create an application that contains a blank template or one pre-configured with layouts and styling for the desired platform.

Before you use the mobile tooling, verify that you have installed all the prerequisite packages and configured your target platforms if needed. For additional information, see Installing the Mobile Tooling.
  1. Scaffold a Hybrid Mobile Application with Yeoman
  2. Build a Hybrid Mobile Application with Grunt
  3. Serve a Hybrid Mobile Application with Grunt

Scaffold a Hybrid Mobile Application with Yeoman

Use the Yeoman generator to create a hybrid mobile application for iOS and Android mobile devices. You can configure the Yeoman generator to scaffold a hybrid mobile application that contains a blank template or one pre-configured with a navigation bar or drawer.

The following image shows the differences between the templates as shown on an Android Nexus 4 emulator using the Android Alta theme. The blank template contains no actual content, and you can configure it however you like. The navBar and navDrawer templates contain sample content and best practices for layouts and styling that you can also modify as needed. You can configure the same application to run on an iOS device, and the application will use the Alta iOS theme.

The image is described in the surrounding text.
  1. At a command prompt, enter yo oraclejet:hybrid with optional arguments to create the Oracle JET application and scaffolding.
    yo oraclejet:hybrid [directory] [--appId=reverse-domain-style-identifier] [--appName=application-display-title] [--template={template-name|template-url}] [--platforms=android,ios]
    

    The following table describes the available options and provides examples for their use.


    Option Description

    directory

    Application location. If not specified, the application is created in the current directory.

    appId

    Application ID entered in reverse domain style: com.mydomain. The appID is equivalent to Package Name on Android and Bundle ID on iOS.

    If not specified, the appId defaults to org.oraclejet.directory, using the current directory or the directory you specified in the scaffolding command.

    For example, if you specified app for the directory, the default appID will be org.oracle.jet.app.

    appName

    Application name displayed on device. To include spaces in the title, use quotes: --appName=”My Sample Application”.

    template

    Template to use for the application. Specify either of the following:

    • template-name

      Predefined template. You can specify blank, navBar , or navDrawer. If you don’t specify a template, your application will be configured with the blank template.

    • template-URL

      URL to zip file containing the name of the zipped application: http://path-to-app/app-name.zip.

    platforms

    Comma-separated list of platform names. You can specify one or both of the following: ios, android.

    If you don’t specify a platform, the command will prompt you for your choice of platform after verifying that the necessary prerequisites are available.


    For example, the following command will create a hybrid mobile application named Sample NavBar in the app directory using the navBar template and targeted for Android devices:

    yo oraclejet:hybrid app --appName="Sample NavBar" --template=navBar --platforms=android
    

    The scaffolding will take some time to complete. When successful, the terminal will display: Done, without errors.

    The new application will have a directory structure similar to the one shown in the following image.

    The image is described in the surrounding text.

    The application folders contain Oracle JET libraries, build scripts, and the application files that you will modify as needed for your own application.


    Directory Description

    bower_components

    Contains the third-party libraries and Oracle JET packages managed by Bower

    hybrid

    Contains the platform-specific files that are merged in with a copy of the application files at build time

    hybrid/config.xml

    Contains the Cordova global configuration settings. You can edit config.xml to specify core Cordova API features, plugins, and platform-specific settings.

    For example, the following settings set the log level to VERBOSE on Android applications and the application’s orientation to landscape only on all platforms.

    <?xml version='1.0' encoding='utf-8'?>
    <widget id="org.oraclejet.hybridnavbar" version="0.0.1" xmlns="http://www.w3.org/ns/widgets" xmlns:cdv="http://cordova.apache.org/ns/1.0">
      <name>hybrid-navBar</name>
      ... contents omitted
      <preference name="LogLevel" value="VERBOSE"/>
      <preference name="Orientation" value="landscape" />
    </widget>
    

    node_modules

    Contains the Node.js modules used by the tooling framework

    scripts

    Contains Oracle JET build scripts

    src

    Site root for your application. Contains the application files that you can modify as needed for your own application.

    The content will vary, depending upon your choice of template. Each template, even the blank one, will contain an index.html file and a main.js RequireJS bootstrap file.

    Other templates may contain view templates and viewModel scripts pre-populated with content. For example, if you specified the navBar template during creation, the js/views and js/viewModels folders will contain the templates and scripts for a hybrid mobile application that uses a navBar for navigation.


  2. In your development environment, update the code for your application as needed. You can find examples that use the navBar and navDrawer templates in the Oracle JET Cookbook at: .

Build a Hybrid Mobile Application with Grunt

Use Grunt with the build and platform options to build a development version of your hybrid mobile application that you can use for testing and debugging.

Change to the application’s root directory and use the grunt build:dev command for each platform that your hybrid mobile application will support.

grunt build --platform={android|ios} [--buildConfig=path/buildConfig.json]

For example, the following command will build the Sample Android Application shown in Scaffold a Hybrid Mobile Application with Yeoman

grunt build --platform=android

The buildConfig.json file contains details that Cordova can use to sign the application. You do not need this file for Android development because the signing details are added automatically during the build. However, you must configure one for testing on an iOS device and when you’re ready to release your application. For additional information, see Packaging and Publishing Hybrid Mobile Applications.

WARNING:

If you use a proxy server, the build command will fail the first time you issue it. To resolve, create a gradle.properties file in your HOME/.gradle directory and rerun the build command. The file should contain the following:
systemProp.http.proxyHost=proxy-server-URL
systemProp.http.proxyPort=80
systemProp.https.proxyHost=proxy-server-URL
systemProp.https.proxyPort=80

The command will take some time to complete. If it’s successful, you’ll see the following message: Done, without errors.

The command will also output the name and location of the built application in platforms/android or platforms/ios.

Note:

You can also use the grunt build command with the :release option to build a release-ready version of your application. For information, see Packaging and Publishing Hybrid Mobile Applications.

Serve a Hybrid Mobile Application with Grunt

Use the Grunt serve command with options to launch your hybrid mobile application in a browser, simulator, or mobile device for testing and debugging. By default, a live reload option is enabled which lets you make changes to your application code that are immediately reflected in the running application.

Enter the following commands at a terminal prompt:
  1. Change to the application’s root directory and use the grunt serve:dev command with options to launch the application.
    grunt serve --platform=ios|android [--web=true --serverPort=server-port-number --livereloadPort=live-reload-port-number --destination=emulator-name|device --disableLiveReload=true]
    

    The following table describes the commonly-used options and provides examples for their use.

    Option Description

    platform

    Desired platform. Enter ios or android.

    web

    Set to true to display the application in the default browser, using the Alta theme (ios or android) appropriate for the specified platform.

    serverPort

    Server port number. If not specified, defaults to 8000.

    livereloadPort

    Live reload port number. If not specified, defaults to 35729.

    destination

    Specify the name of a pre-configured emulator (for example, an Android Virtual Device (AVD) that you named Nexus7 ) to display the application on the specified emulator. If not specified, the application will display on the default Android AVD or iOS Simulator unless you set the web option to true as described above.

    You can also set this to device to send the application to an attached device. However, if you want to send your application to an iOS device, you must take additional steps as described in Packaging and Publishing Hybrid Mobile Applications. Typically, you can develop and test your iOS application in the simulator or web browser until you’re ready to build your release.

    disableLiveReload

    Set to true to disable the live reload feature.

    Disabling live reload can be helpful if you’re working in NetBeans or other IDE and want to use that IDE’s mechanism for loading updated applications.

    The application will launch in a local browser, emulator/simulator, or device depending upon the options you specify. The following table shows examples.

    Command Description

    grunt serve --platform=android --web=true

    Launches the application in the default local browser using the Alta Android theme.

    grunt serve --platform=ios

    Launches the application in the iOS Simulator using the Alta iOS theme.

    grunt serve --platform=android --destination=emulator-name

    Launches the application in the specified emulator. For example, use Nexus7 to specify an AVD that you named Nexus7. The emulator name is case-sensitive.

    grunt serve --platform=android --destination=device

    Launches the application in an attached mobile device.

  2. Update the sample code as needed and save the file.

    If you left live reload enabled, the terminal window updates to reflect that the code has changed. For example, if you save a change to dashboard.html in an application scaffolded with the navBar or navDrawer template, the terminal window outputs the name of the changed file, and the browser updates with the change.

    The following figure shows the grunt serve command output on a Windows machine. In this example, the command uses grunt serve:dev which is functionally equivalent to grunt serve.

    The image is described in the surrounding text.
  3. If you left live reload enabled, press Ctrl+C in the command window and then enter y at the prompt to terminate the batch job.
    You may have to press Ctrl+C a few times before you get the prompt to terminate the job.

Note:

You can also use the grunt serve command with the :release option to build a release-ready version of your application. For information, see Packaging and Publishing Hybrid Mobile Applications.