Getting Started with Oracle JET Hybrid Mobile Application Development

The Oracle JavaScript Extension Toolkit (JET) framework includes support for hybrid mobile application development using Cordova. The framework provides iOS, Android, and Windows 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 Android, iOS, and Windows, you must also install the Android, iOS, and Windows 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
  5. (Optional) Install Windows 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.

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

Note:

  • You no longer need to install ios-sim separately in Cordova iOS 4.0.0 or greater.

  • Ensure that your version of ios-deploy is 1.8.6 or greater.

  • Use the following command to install ios-deploy: sudo npm install -g ios-deploy --unsafe-perm=true --allow-root

Install Windows Tools

To develop applications for the Windows 10 platform, you must install the Windows development environment. Oracle JET tooling requires Microsoft Visual Studio 2015 installed on a supported platform.

Using Cordova’s Windows Platform Guide, install Visual Studio 2015.

Note:

This step is sufficient for developing Windows 10 applications and testing on Windows simulators. If, however, you want to deploy your application to the Windows Store, you must supply a signing certificate. 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 hybrid mobile applications for Android, iOS, and Windows 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, Android, and Windows mobile devices. You can configure the Yeoman generator to scaffold a hybrid mobile application that contains a blank template or one pre-configured with layout styles, 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 index.html but no display and is not shown. The basic:hybrid template adds styling but no sample content, and you can configure it however you like. The navbar:hybrid and navdrawer:hybrid 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 or Windows device, and the application will use the Alta iOS or Windows theme.

The image is described in the surrounding text.

Note:

Do not confuse the basic template which contains no content with the QuickStart Basic sample application in the QuickStart sample collection. The QuickStart Basic sample application uses a navdrawer layout and contains sample content.
  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=application-id] [--appname=application-name] [--template={template-name:[web|hybrid]|template-url}] [--platforms=android,ios,windows|--platform=android|ios|windows]
    

    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.myappname. 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.oraclejet.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 basic, 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 more of the following: ios, android. windows.

    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.

    platform

    Platform name. You can specify one of the following: ios, android. windows.

    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. If the android, ios, or windows platforms are not available, the application will be configured for the browser platform.


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

    yo oraclejet:hybrid app --appname="Sample NavBar" --template=navbar --platform=android
    

    The scaffolding will take some time to complete. When successful, the terminal will display: Your app is ready! Change to your new app directory app and try grunt build and serve...

    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 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

    res

    Contains the application’s icons and splash screen images

    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 nav bar for navigation.

    themes

    Contains the android, ios, web, and windows Alta themes used by the tooling, and you should not modify this folder directly. For information about customizing your application’s themes, see Customizing Themes Using the Tooling Framework.


  2. To add Cordova plugins to your application, change to the application’s hybrid directory and add the plugin: cordova plugin add plugin-name.

    For additional information about adding Cordova plugins to your application, see Cordova Plugins. For help creating your own plugins, see the Plugin Development Guide.

    If you add a Cordova plugin that doesn’t have browser platform support, you can add objects that represent mock data to cordovaMock.js in src/js.

  3. 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 Android, iOS, or Windows 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[:dev] --platform={android|ios|windows} [--build-config=path/buildConfig.json --theme=themename[:android|ios|web|windows]

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 theme defaults to alta:platform, but you can specify an alternate theme. You can also enter a different themename with optional platform for a custom theme as described in Customizing Themes Using the Tooling Framework.

The buildConfig.json file contains details that Cordova can use to sign the application. You do not need this file for Android or Windows 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 hybrid/platforms/android , hybrid/platforms/ios, or hybrid/platforms/windows.

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 Grunt serve to launch your hybrid mobile application in a browser, simulator, or mobile device for testing and debugging. When you serve your application to a browser or emulator, a live reload option is enabled, and changes you make to the code are immediately reflected in the running application.

Enter the following commands at a terminal prompt:

  1. Change to the application’s top level directory and use the grunt serve[:dev] command with options to launch the application.
    grunt serve:[dev] --platform=ios|android|windows [--server-port=server-port-number --livereload-port=live-reload-port-number --destination=emulator-name|browser|device --no-livereload --no-build --theme=themename[:android|ios|windows|web]]
    

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

    Option Description

    platform

    Desired platform. Enter android, ios or windows.

    server-port

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

    livereload-port

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

    destination

    Specify one of the following:

    • emulator-name: Pre-configured emulator (for example, an Android Virtual Device (AVD) that you named Nexus4 ) . If not specified, the application will display on the default Android AVD, iOS Simulator, or Windows Emulator.

    • browser: displays your application in a browser on your local machine.

    • device: Sends the application to an attached device. Be aware, though, 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.

    Note:

    The tooling framework includes shortcuts for the destination options: --browser, --emulator, and --device are functionally equivalent to destination=browser, destination=emulator, and destination=device.

    no-livereload

    Set this option 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.

    no-build

    If you already built your application using grunt build, set this option to disable a re-build. By default, grunt serve invokes grunt build.

    theme

    The theme defaults to alta:platform, but you can specify an alternate theme. You can also enter a different themename with optional platform for a custom theme as described in Customizing Themes Using the Tooling Framework.

    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 --browser

    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 --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 a portion of 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 and --browser which is functionally equivalent to --destination=browser.

    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 serve a release-ready version of your application. For information, see Packaging and Publishing Hybrid Mobile Applications.