Getting Started with Oracle JET Hybrid Mobile Application Development

Oracle JET includes support for hybrid mobile application development using Cordova. The toolkit 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.

Once you have created a hybrid mobile application, added Cordova plugins, and familiarized yourself with Oracle JET’s mobile features, refer to the following information for details about other tasks that you need to do to complete your hybrid mobile application.

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. For information on developing web applications, see Getting Started with Oracle JET Web Application Development

Install the Mobile Tooling

To create Oracle JET hybrid mobile applications, you must first install Cordova on your development machine. To develop hybrid mobile applications for Android, iOS, or Windows, you must also install the Android, iOS, or Windows development tools.

To install the mobile tooling:

If needed, install the tooling prerequisites as described in Install the Prerequisite Packages.

  1. Install Apache Cordova
  2. (Optional) Install Android Development Tools
  3. (Optional) Install iOS Development Tools
  4. (Optional) Install Windows Development Tools

Install Apache Cordova

Install Apache Cordova on your development machine.

Cordova is an open-source cross-platform development framework that enables application developers to use standard web technologies (HTML, CSS, and JavaScript) to develop hybrid mobile applications. JET uses plugins developed with the Apache Cordova framework to access the capabilities of the devices on which your JET mobile application is installed such as, for example, camera and GPS. JET also uses Cordova to build and serve hybrid mobile applications by invoking the Cordova command-line interface that you install with Cordova.

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

[sudo] npm install -g cordova

This installs the Cordova command-line interface and supporting tools that Oracle JET’s CLI invokes when you issue commands such as ojet create and ojet serve. Oracle JET recommends that you keep the Cordova command-line interface up-to-date as newer releases of Cordova provide support for recent versions of mobile operating systems in addition to bug fixes and other enhancements.

Use the following command to update to the latest version of the Cordova command-line interface:

npm install -g cordova@latest

Use the following npm command to view the currently-installed version of the Cordova command-line interface on your system:

cordova --version

Each time that you scaffold a hybrid mobile application for one or more mobile platforms, a platform-specific Cordova module is installed for each platform (Android, iOS, Windows, and so on) that you specify when you scaffold the hybrid mobile application. These platform-specific module versions are separate from each other and separate from the version of the Cordova command-line interface. The following output shows the terminal window output where commands have been issued to retrieve the version of the Cordova command-line interface (7.0.1) and to list the installed and available versions of Cordova platform (android 6.2.3 and so on).

D:\JETapps\apps\JETDocExample\hybrid>cordova --version
7.0.1
...
D:\JETapps\apps\JETDocExample\hybrid>cordova platform
Installed platforms:
  android 6.2.3
  browser 4.1.0
Available platforms:
  blackberry10 ~3.8.0 (deprecated)
  webos ~3.7.0
  windows ~5.0.0

For additional information about managing Cordova platforms, see Platforms and Plugins Version Management and for an overview of Cordova, see Overview in Cordova’s documentation.

Install Android Development Tools

Install the Android SDK to deploy a JET hybrid mobile application to Android devices.

The Android SDK provides the tools that build and package your application into an .APK file (the file type that installs applications on Android devices), an emulator to create Android Virtual Devices (AVD) where you can test your application if you do not have access to a physical Android device, and an OEM USB driver to connect your development machine to a physical Android device through a USB cable if you do have a device. This last option enables you to deploy an application from your development machine to the Android device.

Android Studio, Google’s IDE for Android development, includes the Android SDK in its installation and provides wizard options that simplify the management of the SDK platforms and tools that you need.

Install Android Studio, and the Android SDK that it includes, by downloading the installation file from https://developer.android.com/studio/index.html. The Android Developer’s website provides installation instructions for Windows, Mac, and Linux. See https://developer.android.com/studio/install.html.

Once you have installed Android Studio, perform the tasks described in the following topics:

Android requires that all .APK files be digitally signed with a certificate before they can be installed. For apps in development, the Android SDK automatically creates a debug keystore and certificate and sets the keystore and key passwords the first time that you build an .APK file. On macOs and Unix, it creates these resources in $HOME/.android/debug.keystore. On Windows, they are in the directory referenced by the %USERPROFILE% variable (for example, C:\Users\JDOE\.android).

When you have completed development and want to sign and package the Android app for distribution, see Packaging a Hybrid Mobile App on Android.

Install an Emulator Accelerator

You can accelerate the performance of the emulator on Intel x86–based development machines by installing an emulator accelerator.

The emulator accelerator speeds up the performance of the emulator and the AVDs that it emulates by allocating additional resources from your development machine. Once installed, the accelerator appears in the SDK Tools list of the SDK Manager, as shown in the image below. Use Android Studio’s Tools, Android, and SDK Manager menu options to open the SDK Manager or the icon that appears on the Android Studio toolbar.

Make sure that the update site for the emulator accelerator that you want to download is selected in the SDK Update Sites tab as shown. Once downloaded, execute the installer. See https://developer.android.com/studio/run/emulator-acceleration.html#accel-vm.

Create an Android Virtual Device

An Android Virtual Device (AVD) replicates an Android device on your development computer. It is a useful option for testing, especially if you only have access to one or a limited range of physical Android devices.

The AVD Manager that you launch from Android Studio by clicking Tools, Android, and AVD Manager has a range of ready-to-use virtual devices, mostly of those devices developed by Google itself, such as the Nexus and Pixel XL range. Other Android device vendors, such as Samsung, provide specifications on their websites that you can use to create the AVD yourself.

Google maintains documentation describing how to manage AVDs. See https://developer.android.com/studio/run/managing-avds.html.

To create an AVD:

  1. In Android Studio, launch the Android Virtual Device Manager by selecting Tools > Android > AVD Manager.

  2. In the Your Virtual Devices screen, click Create Virtual Device.

  3. In the Select Hardware screen, select a phone device, such as Pixel, and then click Next.

  4. In the System Image screen, click Download for one of the recommended system images. Agree to the terms to complete the download.

  5. After the download completes, select the system image from the list and click Next.

  6. On the next screen, leave all the configuration settings unchanged and click Finish.

  7. In the Your Virtual Devices screen, select the device you just created and click Launch this AVD in the emulator.

Set Up Your Android Device to Install an App from Your Development Machine

You can install your app directly from your development machine to your Android device by configuring the Android device and connecting it to your development machine using a USB cable.

To set up your Android device:

  1. Connect your device to your development machine with a USB cable. If you are developing on Windows, you might need to install the appropriate USB driver for your device. For help installing drivers, see the OEM USB Drivers document.

  2. Enable USB debugging on your device by going to Settings > Developer options.

    Note:

    On Android 4.2 and newer, Developer options is hidden by default. To make it available, go to Settings > About phone and tap Build number seven times. Return to the previous screen to find Developer options.

Configure Gradle Proxy Settings

Gradle is the tool that the Android SDK invokes to build the apps that you deploy to your AVD or Android device.

If you work inside a corporate network, create a gradle.properties file in your ~/.gradle directory that includes the following properties so that you can successfully serve your app to the AVD or physical device.

systemProp.http.proxyHost=www-proxy.server.url.com
systemProp.http.proxyPort=proxy-port-number
systemProp.https.proxyHost=www-proxy.server.url.com
systemProp.https.proxyPort=proxy-port-number

If you are a Windows user, you locate your ~/.gradle directory by navigating to %USERPROFILE%\.gradle. If you are a macOS or Linux user, navigate to ~/.grade.

Configure Environment Variables to Reference JDK and Android SDK Installations

To function correctly, the Cordova CLI that the Oracle JET CLI communicates with requires that you configure certain environment variables.

The Cordova CLI attempts to set these environment variables for you, but in certain cases you may need to set them manually. In any event, it is a good idea to review and confirm the values of the following environment variables before you start development:

  • Set JAVA_HOME to the location of your JDK installation

  • Set ANDROID_HOME to the location of your Android SDK installation

We also recommend that you add the Android SDK's tools, tools/bin, and platform-tools directories to your PATH environment variable.

The process to set the environment variables depends upon your development environment:

  • Windows

    Set the variables permanently in Control Panel > System and Security > System > Advanced System Settings > Environment Variables.

    For example, to include the Android SDK's tools and platform-tools directories in your PATH environment variable, modify the entry that the Environment Variables dialog displays to include entries similar to the following:

    Path=C:\Users\JET\AppData\Local\Android\sdk\tools;C:\Users\JET\AppData\Local\Android\sdk\platform-tools;C:\Users\JET\AppData\Roaming\npm

    To set the JAVA_HOME and ANDROID_HOME environment variables, click New in the Environment Variables dialog and set the values of the variables to the location of the JDK and Android SDK locations, as shown in the following image.

    Description of GUID-ABCEA5BA-8070-4DC2-95D0-3BFD4014AE80-default.png follows
    Description of the illustration GUID-ABCEA5BA-8070-4DC2-95D0-3BFD4014AE80-default.png

    If you have opened a command window, close it and open a new one for the change to take effect.

  • Macintosh and Linux

    On Mac and Linux systems, the settings depend upon your default shell. For example, on a Mac system using the Bash shell, add the following lines in ~/.bash_profile:

    export JAVA_HOME=/Development/jdkInstallDir/
    export ANDROID_HOME=/Development/android-sdk/
    

    To update your PATH environment variable, add a line resembling the following where you substitute the paths with your local Android SDK installation's location:

    export PATH=${PATH}:/Development/android-sdk/platform-tools:/Development/android-sdk/tools
    

    Reload your terminal to see this change reflected or run the following command:

    $ source ~/.bash_profile
    

    On a Linux system using C Shell, you would use the following format:

    setenv JAVA_HOME=/Development/jdkInstallDir/
    setenv ANDROID_HOME=/Development/android-sdk/
    

    Reload your terminal to see this change reflected or run the following command:

    ~/.cshrc 
    

Install iOS Development Tools

To develop applications for the iOS platform, you must install the Xcode development environment from the App Store which is only available on macOS.

After installing Xcode, execute the following command in a terminal window to install the Xcode command line tools:

xcode-select –install

These steps are sufficient for developing iOS applications and testing on iOS simulators. If, however, you want to use an actual iOS device for testing or to publish your application to the App Store, you must join the Apple iOS Developer program and create an appropriate provisioning profile. For additional information, see Maintaining Identifiers, Devices, and Profiles in Apple’s documentation. For details about using the Oracle JET tooling to package and deploy your hybrid mobile application, see Packaging a Hybrid Mobile App on iOS.

In addition you must install a tool that is used by the Oracle JET CLI to deploy apps to iOS devices by executing the following command in a terminal window:

sudo npm install -g ios-deploy --unsafe-perm=true --allow-root

Once you have installed the iOS development tools, you can create a hybrid mobile application, as described in Create a Hybrid Mobile Application.

Install Windows Development Tools

JET hybrid mobile apps for Windows devices must be developed on computers that run the Windows 10 operating system.

JET supports the creation of hybrid mobile apps that are Universal Windows Platform (UWP) apps. UWP is the platform for Windows 10. For more information, see What's a Universal Windows Platform (UWP) app? in Microsoft’s documentation.

Enable Developer Mode on Windows 10

Developer mode allows you to install any signed and trusted apps to your Windows development machine, whereas the default Windows 10 setting only permits the installation of apps from the Windows Store.

  1. From the For developers settings dialog, choose Developer mode.
  2. Read the disclaimer in the dialog that appears and click Yes to accept the change.

Note:

If your device is owned by an organization, some options might be disabled by your organization. Contact your system administrator to ensure you have the options enabled that you require.

Figure 2-1 Enable Developer Mode on a Windows 10 Computer

The configuration screen in Windows 10 where you select Developer mode.

For information about Developer mode, and other settings that configure development on Windows 10 computers, see https://docs.microsoft.com/en-us/windows/uwp/get-started/enable-your-device-for-development.

Install Visual Studio

Install Visual Studio as it includes the Windows 10 SDK and the Universal Windows App Development Tools that you require to develop and deploy a JET hybrid mobile application on your computer.

Microsoft offers a number of editions of Visual Studio. The Visual Studio Community edition is a free, fully-featured IDE for students, open-source and individual developers. Visual Studio can be downloaded from https://www.visualstudio.com/vs/. During download and installation, select the Universal Windows Platform development workload and the latest version of the Windows 10 SDK that appears under the Optional list of items that you can install with the workload, as shown in the following image.

Figure 2-2 Installing Visual Studio

The Workloads screen of the install wizard for Visual Studio where you select the Windows 10 SDK as an optional install.

Run Visual Studio after you install it to execute any required setup tasks. This prompts you to enable Developer mode, if you have not already enabled this mode on your computer.

Install a Personal Information Exchange File in Your Computer’s Certificate Store

Install a personal information exchange file (.PFX) in certificate stores on your Windows 10 computer. The PFX file packages a private key file and a certificate file that you use to sign your app.

This is a one-time task that, once complete, enables you to build and serve JET hybrid mobile applications in debug mode on your Windows 10 computer. You also require a PFX file to sign your JET hybrid mobile application when you complete development and want to distribute it.

The following procedure describes how to create PVK and CER files without password protection that you package into a PVK file that is also without password protection. For more information about the switches and arguments supported by the Microsoft tools that you use to create and package a PFX file, see the following Microsoft documentation:

For more information about packaging a completed JET hybrid app for Windows, see Packaging a Hybrid Mobile App on Windows.

To create and install a PFX file:

  1. At a command prompt with Administrator privileges, enter the following commands:
    1. Change to the directory that contains the Windows SDK. For example:
      chdir "C:\Program Files (x86)\Windows Kits\10\bin\x64"
    2. Use the MakeCert tool to create certificate files with the specified parameters. For example:
      makecert.exe -sv C:\aDirectory\doc.pvk -n "CN=Doc Example,OU=JET,O=Oracle,C=US" -r -h 0 -eku "1.3.6.1.5.5.7.3.3,1.3.6.1.4.1.311.10.3.13" C:\aDirectory\doc.cer
    3. Package the resulting certificate files into a PFX file. For example:
      pvk2pfx.exe -pvk C:\aDirectory\doc.pvk -spc C:\aDirectory\doc.cer -pfx C:\aDirectory\doc.pfx
    This creates a PFX file named doc.pfx in the C:\aDirectory\ directory.
  2. Install the PFX file in the following Certificate Stores on your computer
    Store Location Certificate Store
    Current User Personal
    Current User Trusted People
    Local Machine Trusted People
  3. To do this, double-click the PFX file to invoke the Certificate Import Wizard, choose the appropriate store location (for example, Current User) and click Next to proceed to the page where you choose the Certificate Store, as shown by the following figure where the Trusted People certificate store is selected.

    Note:

    The file created in our previous example is not password-protected, so leave the Password input field blank in the Private key protection page of the wizard.
    Certificate Import Wizard that Assists with Installation of Certificate Files.
  4. Click Finish to complete the installation of the certificate in the certificate store and repeat the process to install the PFX file in the remaining certificate stores.

Create a Hybrid Mobile Application

Use the Oracle JET mobile tooling commands to create, build, run, and customize 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 Install the Mobile Tooling.
  1. Scaffold a Hybrid Mobile Application with the Oracle JET CLI
  2. (Optional) Build a Hybrid Mobile Application with the Oracle JET CLI
  3. Serve a Hybrid Mobile Application with the Oracle JET CLI
  4. Review Your Application Settings in the config.xml File
  5. Change the Splash Screen and App Launcher Icon

Note:

You can add hybrid platforms (Android, iOS, and Windows) to an existing web application. See Add Hybrid Mobile Features to Web Applications.

Scaffold a Hybrid Mobile Application with the Oracle JET CLI

Use the Oracle JET CLI to scaffold a hybrid mobile application for iOS, Android, and Windows mobile devices. You can scaffold the application to contain a blank template or one pre-configured with layout styles, a navigation bar, or a navigation drawer. After scaffolding, you can modify the app as desired.

Oracle JET provides a set of templates designed for hybrid mobile apps in addition to the templates for web apps. JET uses the hybrid version of the template by default when scaffolding a hybrid mobile app.

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 UI features, and is not shown in the image that follows. The basic template adds styling but no sample content, and can be used as the basis for your app if you have no navigational requirements or if you want to design the entire app yourself. The navbar and navdrawer templates contain sample content and best practices for layouts and styling that you can also modify as needed. The same app will run on any Android, iOS, or Windows emulator or device, using the appropriate Alta theme for the platform.

Note:

Do not confuse the basic template which contains no content with the QuickStart Basic sample application in the NetBeans JET Support plugin. The QuickStart Basic sample application uses a navdrawer layout and contains sample content.

At a command prompt, enter ojet create --hybrid with optional arguments to create the Oracle JET application and scaffolding.

ojet create [directory] --hybrid 
                    [--appid=application-id] [--appname=application-name]
                    [--template={template-name:[web|hybrid]|template-url|template-file}]
                    [--platforms=android,ios,windows|--platform=android|ios|windows]

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

Tip:

You can also enter ojet help at a terminal prompt to get additional help about the Oracle JET CLI.
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 directory you specified in the scaffolding command.

For example, if you specified MyApp for the directory, the default appid will be org.oraclejet.MyApp.

appname

Application name displayed on device. To include spaces in the title, use quotes: --appname="My Sample Application". If not specified, the appid defaults to the directory you specified in the scaffolding command.

template

Template to use for the application. Specify one 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.

  • template-file

    Path to zip file on your local file system containing the name of a zipped application: "path-to-app/app-name.zip". For example:
    --template="C:\Users\SomeUser\app.zip"
    --template="/home/users/SomeUser/app.zip"
    --template="~/projects/app.zip"
    

platforms

Comma-separated list of platform names. You can specify one or more of the following: ios, android, or windows without spaces. For example: 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.

platform

Platform name. You can specify one of the following: ios, android, or 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.

WARNING:

Do not use internal in the appid. This is one of a number of undocumented Cordova reserved words, and the scaffolding will fail with the following error: App id contains a reserved word, or is not a valid identifier. To work around this limitation:
  1. Scaffold your application with a temporary appid: appid=com.mycompany.temp.

  2. Change to the application’s hybrid directory and edit config.xml to replace the temporary appid with the new appid: id="com.mycompany.internal".

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

ojet create MySampleApp --hybrid --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 MySampleApp...

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

The application folders contain the application and configuration files that you will modify as needed for your own application.

Directory Description

hybrid

Contains platform-specific files that are merged in with a copy of the application files at build time. Most of the files in this directory are staging files that you should not commit to your source control system. One exception is the hybrid/config.xml file.

hybrid/config.xml

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

For example, the following entry sets the application’s orientation to landscape-only on all platforms.

<?xml version='1.0' encoding='utf-8'?>
<widget
    ... contents omitted
    <preference name="Orientation" value="landscape" />
</widget>

Commit the config.xml file to your source control system, if you use one. For more information about the config.xml file, see Review Your Application Settings in the config.xml File.

scripts

Contains the oraclejet-build.js and oraclejet-serve.js files that you can modify to customize your application’s build and serve steps. See Customize a Web Application’s Build Behavior and Customize a Web Application’s Serve Behavior.

node_modules

Contains the Node.js modules used by JET tooling.

src

Site root for your application. Contains the application files that you can modify as needed for your own application and should be committed to source control.

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.

Modify the Hybrid Mobile Application’s File Structure

You can modify your scaffolded application’s file structure if the default structure doesn’t meet your needs.

The oraclejetconfig.json file in your application’s top level directory contains the default source and staging file paths that you can modify.

{
  "paths": {
    "source": {
      "common": "src",
      "web": "src-web",
      "hybrid": "src-hybrid",
      "javascript": "js",
      "styles": "css",
      "themes": "themes"
    },
    "staging": {
      "web": "web",
      "hybrid": "hybrid",
      "themes": "themes"
    }
  },
"serveToBrowser": "chrome",
"generatorVersion": "x.x.x"
}

To change the hybrid mobile application’s file structure:

  1. In your application’s top level directory, open oraclejetconfig.json for editing.
  2. In oraclejetconfig.json, change the paths as needed and save the file.

    For example, if you want to change the default styles path from css to app-css, edit the following line in oraclejetconfig.json:

    "styles": "app-css"
    
  3. Rename the directories as needed for your application, making sure to change only the paths listed in oraclejetconfig.json. For example, if you changed styles to app-css in oraclejetconfig.json, change the application’s css directory to app-css.
  4. Update your application files as needed to reference the changed path

    For example, if you modify the path to the CSS for your application, update the links appropriately in your application’s index.html.

    <link rel="icon" href="app-css/images/favicon.ico" type="image/x-icon" />
    
        <!-- This is the main css file for the default Alta theme -->
        <!-- injector:theme -->
        <link rel="stylesheet" href="app-css/libs/oj/vx.x.x/alta/oj-alta-min.css" type="text/css"/>
        <!-- endinjector -->
        
        <!-- This contains icon fonts used by the starter template -->
        <link rel="stylesheet" href="app-css/demo-alta-site-min.css" type="text/css"/>
    
        <!-- This is where you would add any app specific styling -->
        <link rel="stylesheet" href="app-css/override.css" type="text/css"/>
    
To use the new paths, in your application’s top level directory, build your application as described in Build a Hybrid Mobile Application with the Oracle JET CLI.

Build a Hybrid Mobile Application with the Oracle JET CLI

Use Oracle JET CLI to build your Android, iOS, or Windows hybrid mobile application for testing and debugging.

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

ojet build [android|ios|windows]
           [--build-config=path/buildConfig.json --destination=device|emulator
            --theme=themename[:android|ios|web|windows] --themes=theme1,theme2,... 
            --sass
            --platform-options="string"]

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

Tip:

You can also enter ojet help at a terminal prompt to get help for specific Oracle JET CLI options.
Option Description

[android|ios|windows]

Desired platform. Enter android, ios, or windows.

build-config

Path to buildConfig.json. The buildConfig.json file contains details that Cordova can use to sign the application.

You do not need this file when building a debug version of your app for Android or Windows, or if you are building your app for deployment to an iOS simulator. However, you must configure one for testing on an iOS device and when you’re ready to release your Android, iOS, or Windows application. For additional information, see Packaging and Publishing Hybrid Mobile Applications.

destination

Required for iOS applications. Specify one of the following:

  • emulator: builds your application for deployment to the iOS Simulator.

  • device: builds your application for deployment to an iOS device. Be aware, though, if you want to deploy your application to an iOS device, you must take additional steps as described in Packaging a Hybrid Mobile App on iOS. Typically, you can develop and test your iOS application in the simulator or web browser until you’re ready to build your release.

device

Equivalent to destination=device.

emulator

Equivalent to destination=emulator.

theme

Theme to use for the application. The theme defaults to alta:platform, but you can specify an alternate theme, such as a custom theme as described in Customizing Themes Using the Tooling.

themes

Themes to include in the application, separated by commas without spaces.

If you don’t specify the --theme flag as described above, Oracle JET will use the first element that you specify in --themes as the default theme.

sass

Manages Sass compilation. If you add Sass and specify the --theme or --themes option, Sass compilation occurs by default and you can use --sass=false or --no-sass to turn it off. If you add Sass and do not specify a theme option, Sass compilation will not occur by default, and you must specify --sass=true or --sass to turn it on. For more information, see Customizing Themes Using the Tooling.

platform-options

Platform-specific options that will pass verbatim to the Cordova CLI.

This option is typically required for Windows device deployments or if a Cordova plugin contains multiple static libraries for different CPUs. If the value passed contains a quoted string, the quotation marks must be escaped.

For example, you can use platform-options to specify Windows architectures. By default, the architecture defaults to anycpu.

To specify a single architecture, use the --arch option and specify arm, x86, x64, or anycpu.
--platform-options="--arch arm|x86|x64|anycpu"
To specify multiple architectures, use the --archs option with a space-separated list passed in as a quoted string. Note that you must escape the quotation marks as shown below.
--platform-options="--archs=\"arm x86 x64\""

For example, the following command will build the sample Android application shown in Scaffold a Hybrid Mobile Application with the Oracle JET CLI

ojet build android

The command will take some time to complete. If it’s successful, you’ll see the following message: Done. The command will also output the name and location of the built application in hybrid/platforms/android , hybrid/platforms/ios, or hybrid/platforms/windows.

By default ojet build creates a debug version of your application. You can also use the ojet build command with the –-release option to build a release-ready version of your application. For information, see Packaging and Publishing Hybrid Mobile Applications.

WARNING:

If you use a proxy server and specify the Android platform, the build command will fail the first time you issue it. To resolve this, 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

Customize a Hybrid Mobile Application’s Build Behavior

Edit oraclejet-build.js to modify default build behavior. For example, you can add additional libraries to your application or change the default markers used to inject links into the application’s index.html during build time.

The Oracle JET tooling defines default build and serve behavior in node_modules/@oracle/oraclejet-tooling/lib/defaultconfig.js. The first part of the file contains the default build configuration, including entries for application paths and other options used during the build process. To modify defaults or add your own, edit oraclejet-build.js and remove comments from the options that you want to configure. The file contains detailed instructions for each configurable option.

Oracle JET will merge the options with the default configuration during the build. However, be aware that fileList options will completely replace the corresponding option in the default configuration and will not be merged.

To customize build behavior:

  1. Open scripts/config/oraclejet-build.js for editing in your favorite text editor.
  2. Identify the entry that you want to change and remove the comments (//) preceding each line.

    For example, to add a custom library to the build’s staging directory for hybrid applications, remove the comments from the following section in oraclejet-build.js as shown below:

    /**
     * This is the hybrid specific configuration. You can specify configurations targeted only hybrid apps. 
     * The hybrid specific configurations will override the general configuration. 
     */
    hybrid: {
      copyCustomLibsToStaging: {
        fileList: [
          {
            cwd:'node_modules/oraclejet/',
            src: ['*'],
            dest: 'hybrid/www/js/libs/oraclejet'
          }
        ]
      }
    }
    
  3. Edit the options as desired and save the file.

    For example, to add a custom library named my_custom_module, place the module in node_modules, and edit the copyCustomLibsToStaging entry:

    hybrid: {
      copyCustomLibsToStaging: {
        fileList: [
          {
             cwd:'node_modules/my_custom_module/',
             src: ['*'],
             dest: 'hybrid/js/libs/my_custom_module'
          }
        ]
      }
    }
    
  4. Repeat the previous step for each option that you want to modify.
Test your changes by running Build a Hybrid Mobile Application with the Oracle JET CLI with appropriate options.

Serve a Hybrid Mobile Application with the Oracle JET CLI

Use Oracle JET CLI 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.

At a command prompt, change to the application’s top level directory and use the ojet serve command with options to launch the application.

ojet serve [ios|android|windows]
           [--build-config=path/buildConfig.json
            --server-port=server-port-number --livereload-port=live-reload-port-number
            --destination=emulator[:emulator-name]|browser[:browser-name]|device[:device-name]|server-only
            --livereload --build
            --theme=themename[:android|ios|windows|web]] --themes=theme1,theme2,... 
            --sass
            --platform-options="string"]

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

Tip:

You can also enter ojet help at a terminal prompt to get help for specific Oracle JET CLI commands.
Option Description

[ios|android|windows]

Desired platform. Enter android, ios, or windows.

build-config

Specify the path to buildConfig.json. The buildConfig.json file contains details that Cordova can use to sign the application.

You do not need this file when building a debug version of your application for Android or Windows, or if you are building your app for deployment to an iOS simulator. However, you must configure one for testing on an iOS device and for pre-release testing of your Android, iOS or Windows application. For additional information, see Packaging and Publishing Hybrid Mobile Applications.

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: Displays your application in the default Android AVD, iOS Simulator, or Windows Emulator.

    To use a different emulator, append its name to the emulator option: --destination=emulator:emulator-name.

    Tip:

    You can view the list of available emulators for each platform by invoking the following from your app's top-level folder:

    hybrid/platforms/{platform}/cordova/lib/list-emulator-images

    where {platform} is one of android, ios, or windows.

  • browser: Displays your application in the Chrome browser on your local machine.

    If you don’t have Chrome installed or want to use a different browser, append the name of the desired browser to the browser option:

    --destination=browser:firefox|edge|ie|opera|safari|chrome
    

    Tip:

    To change your application’s default browser from Chrome, open oraclejetconfig.json in the application's top level directory and change the name of the browser in defaultBrowser. For example, to change the default browser to Firefox, edit oraclejetconfig.json as shown below.

    "defaultBrowser": "firefox"
    
  • device: Sends the application to an attached device.

    Optionally, append the name of the device to device option: --destination=device:myDevice.

    Note:

    If you want to send your application to an iOS device, you must take additional steps as described in Packaging a Hybrid Mobile App on iOS.
  • server-only: Serves the application, as if to a browser, but does not launch a browser. Use this option in cloud-based development environments so that you can attach your browser to the app served by the development machine.

browser[=browser-name]

Equivalent to destination=browser[:browser-name].

emulator[=emulator-name]

Equivalent to destination=emulator[:emulator-name].

device[=device-name]

Equivalent to destination=device[:device-name].

server-only

Equivalent to destination=server-only.

livereload

Enable the live reload feature. Live reload is enabled by default (--livereload=true).

Use --livereload=false or --no-livereload to disable the live reload feature.

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

build

Build the app before you serve it. By default, an app is built before you serve it (--build=true).

Use --build=false or --no-build to suppress the build if you’ve already built the application and just want to serve it.

theme

Theme to use for the application. 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 .

themes

Themes to use for the application, separated by commas.

If you don’t specify the --theme flag as described above, Oracle JET will use the first element that you specify in --themes as the default theme. Otherwise Oracle JET will build the application with the theme specified in --theme.

sass

Manages Sass compilation. If you add Sass and specify the --theme or --themes option, Sass compilation occurs by default and you can use --sass=false or --no-sass to turn it off. If you add Sass and do not specify a theme option, Sass compilation will not occur by default, and you must specify --sass=true or --sass to turn it on. For more information, see Customizing Themes Using the Tooling .

Note:

The option that you choose controls both Sass compilation in the build step and Sass watch in the serve step.

platform-options

Platform-specific options that will pass verbatim to the Cordova CLI.

This option is typically required for Windows device deployments or if a Cordova plugin contains multiple static libraries for different CPUs. If the value passed contains a quoted string, the quotation marks must be escaped.

For example, you can use platform-options to specify Windows architectures. By default, the architecture defaults to anycpu.

To specify a single architecture, use the --arch option and specify arm, x86, x64, or anycpu.
--platform-options="--arch arm"

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

ojet serve windows -–browser=firefox

Launches a Windows version of the application in the Firefox browser.

ojet serve ios

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

ojet serve android --destination=emulator:MyEmulator

Launches the application in the Android emulator using the AVD named “MyEmulator”. The emulator name is case-sensitive.

ojet serve android --device

Launches the application on the attached Android mobile device.

The terminal will also output the names of the files as they are loaded. If your application contains multiple views, the output will reflect the names of the views and associated files as you navigate through the application.

WARNING:

If you specify the Android platform, use a proxy server and skipped the ojet build step, the serve command will fail the first time you issue it. To resolve this, create a gradle.properties file in your HOME/.gradle directory and rerun the serve 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

Behavior of Live Reload When Enabled

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 or emulator/simulator updates with the change. Live reload is disabled when you serve an application to a device.

To terminate the batch job when using live reload, press Ctrl+C in the command window and then enter y if prompted to terminate the batch job.

Note:

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

Customize a Hybrid Mobile Application’s Serve Behavior

Edit oraclejet-serve.js to modify default serve behavior. For example, you can add your own watch tasks or specify actions specific to web or hybrid applications.

Oracle JET tooling defines default build and serve behavior in node_modules/oraclejet-tooling/lib/defaultconfig.js. The second half of the file contains the default serve configuration, including entries for application paths and other options used during the serve process. To modify defaults or add your own, edit oraclejet-serve.js and remove comments from the options that you want to configure. The file contains detailed instructions for each configurable option.

Oracle JET will merge the options with the default configuration during the build. However, be aware that rewriting the three default watch targets (sourceFiles, sass, and themes) can result in unpredictable behavior.

To customize serve behavior:

  1. Open scripts/config/oraclejet-serve.js for editing in your favorite text editor.
  2. Identify the entry that you want to change and remove the comments (//) preceding each line that you want to include.

    For example, to define one or more shell commands that you want to execute after the application is served and you modify a source file, you can edit the sourceFiles option in the watch sub task. Remove the comments from the highlighted lines as shown below.

    // // Sub task watch default options
           watch: {
             sourceFiles:
             {
        //     files: [],
        //     options: {
        //       livereload: true
        //     }
             },
    
        //   sass: {
        //     files: [],
        //     commands: ['compileSass']
        //   },
    
        //   themes: {
        //     files: [],
        //     options: {
        //       livereload: true
        //     },
        //     commands: ['copyThemes']
        //   },
          }
    
  3. Edit the options as desired and save the file.
    For command options, add one or more commands, each surrounded by single quotes and separated by commas. For example, the following code snippet adds node --version and npm --version to the commands option in the sourceFiles sub task. Add a comma to the closing braces.
         watch: {
           sourceFiles:
           {
        //     files: [],
        //     options: {
        //       livereload: true
        //     },
                   commands: ['node --version', 'npm --version']
           },
           ... contents omitted
         },
    
Test your changes by running Serve a Hybrid Mobile Application with the Oracle JET CLI with appropriate options. When you change one of the source files, the terminal output will display the output of the node --version and npm --version commands and reload the page.

Review Your Application Settings in the config.xml File

The AppRootDir/hybrid/config.xml file contains a number of default settings that you may want to review and modify before you package and publish your app for distribution to end users.

You can configure entries that affect the behavior of your app across all platforms and entries that are applied only to a specific platform.

Examples of entries for all platforms that you may want to modify in your file before you publish your app include the following:

  • Attribute values of the widget element. Specifically, the values for the id and version attributes.

    The value of the id attribute determines the unique identifier for this app. By default, JET apps use a combination of reverse domain notation with the oraclejet.org domain name as input and the app’s short name. Change this to use, for example, the reverse of your company’s domain name.

  • The value of the version attribute identifies the version number of your app to end users. It appears, for example, on the App Info screen on Android devices. Change it to an appropriate value.

  • Value for the name element. This is the name of the app displayed on the springboard of your user's mobile device and in the app stores.

Apart from these generic settings that affect your app irrespective of the platform where it is deployed (Android, iOS, or Windows), you can configure a range of other entries in the config.xml file that set preferences for your app on specific platforms.

The following example AppRootDir/hybrid/config.xml file displays a number of illustrative examples.

<?xml version='1.0' encoding='utf-8'?>
<widget id="org.oraclejet.docexample" version="1.0.0" xmlns="http://www.w3.org/ns/widgets"
        xmlns:cdv="http://cordova.apache.org/ns/1.0">
  <name>docexample</name>
  <description>A sample Oracle JavaScript Extension Toolkit (JET) mobile app based on Cordova</description>
  <author email="undefined" href="http://www.oraclejet.org">Oracle Jet Team</author>
  <content src="index.html"/>
  <plugin name="cordova-plugin-whitelist" spec="1"/>
  <access origin="*"/>
  <allow-intent href="http://*/*"/>
  ...
  <allow-intent href="geo:*"/>
  <platform name="windows">
    <preference name="windows-target-version" value="10.0"/>
    <icon src="res/icon/windows/Square30x30Logo.scale-100.png" width="30" height="30"/>
    ...
    <splash src="res/screen/windows/SplashScreenPhone.scale-240.png" width="1152" height="1920"/>
  </platform>
  <platform name="android">
    <allow-intent href="market:*"/>
    <preference name="DisallowOverscroll" value="true"/>
<!-- The following entry displays your app using the full screen of the Android device and thus hides the Android 
                                                                    device’s status bar and menu button.-->   
<preference name="Fullscreen" value="true" />
    <icon src="res/icon/android/icon-ldpi.png" width="36" height="36"/>
    ...
    <splash src="res/screen/android/splash-port-xxxhdpi.9.png" density="port-xxxhdpi"/>
  </platform>
  <platform name="ios">
    <allow-intent href="itms:*"/>
    <allow-intent href="itms-apps:*"/>
    <preference name="Orientation" value="all"/>
    <icon src="res/icon/ios/icon-small.png" width="29" height="29"/>
    ...
    <splash src="res/screen/ios/Default-Portrait~ipad.png" width="768" height="1024"/>
  </platform>
  ...
</widget>

For more information about the AppRootDir/hybrid/config.xml file, see https://cordova.apache.org/docs/en/latest/config_ref/.

Change the Splash Screen and App Launcher Icon

Replace the JET-provided images with those that you want your app to use as a splash screen or an app launcher icon.

The default splash screen behavior of your app depends on the platform where you run the app. On Android, for example, the default behavior is to display a white screen. JET provides a set of splash screen images for each platform that can be used in your app. These images are stored in the following sub-directories of your app’s hybrid directory.

AppRootDirectory/hybrid/res/screen
+---android
|       splash-land-hdpi.9.png
|         ...
|       splash-port-xxxhdpi.9.png
|
+---ios
|       Default-568h@2x~iphone.png
|         ...
|       Default~iphone.png
|
\---windows
        SplashScreen.scale-100.png
        SplashScreenPhone.scale-240.png

To use these splash screens, install the cordova-plugin-splashscreen plugin by executing the following command:

ojet add plugin cordova-plugin-splashscreen

You can replace the JET-provided splash screen images with your own images, matching the names and sizes. You can change the behavior of the splash screen by configuring your app’s AppRootDir/hybrid/config.xml file. The following example shows how you display the splash screen for 4000 milliseconds.

  <preference name="SplashScreenDelay" value="4000" />

For more information about the plugin, including how to configure its behavior plus platform-specific information, see https://cordova.apache.org/docs/en/latest/reference/cordova-plugin-splashscreen/.

JET provides a set of app launcher icons for each platform that can be used in your app. To use an alternative app launcher icon to the JET-provided icons, replace the images in the following directories.

AppRootDir/hybrid/res/icon
+---android
|       icon-hdpi.png
|       ...
|       icon-xxxhdpi.png
|
+---ios
|       icon-40.png
|       ...
|       icon@2x.png
|
\---windows
        Square150x150Logo.scale-100.png
        ...
        Wide310x150Logo.scale-240.png

Both the splash screen and app launcher icons that your app uses are referenced from your app’s AppRootDir/hybrid/config.xml file, as shown by the following example excerpts.

<platform name="windows">
        ...
        <icon src="res/icon/windows/Square30x30Logo.scale-100.png" width="30" height="30"/>
        ...
        <splash src="res/screen/windows/SplashScreen.scale-100.png" width="620" height="300"/>

<platform name="android">
        ...
        <icon src="res/icon/android/icon-ldpi.png" width="36" height="36"/>
        ...
        <splash src="res/screen/android/splash-land-ldpi.9.png" density="land-ldpi"/>
        ...
<platform name="ios">
        ...
        <icon src="res/icon/ios/icon-small.png" width="29" height="29"/>
        ...
        <splash src="res/screen/ios/Default@2x~iphone.png" width="640" height="960"/>
        ...

For more information about icons and their entries in the config.xml file, see https://cordova.apache.org/docs/en/latest/config_ref/images.html.

Accessing Mobile Device Services Using Cordova Plugins

You can enable user access to device features, such as camera, geolocation and the local file system, by including Cordova plugins into your JET app.

About Apache Cordova and Cordova Plugins

JET uses plugins developed with the Apache Cordova framework to access the capabilities of the devices on which your hybrid mobile application is installed.

Apache Cordova is an open-source cross-platform development framework that enables application developers to use standard web technologies (HTML, CSS, and JavaScript) to develop hybrid mobile applications. A hybrid mobile application refers to mobile applications that are native applications which are installed onto mobile devices in the usual manner, but which use a web view to render the UI rather than using the platform's native UI components. For additional information about Apache Cordova, see the Overview page at http://cordova.apache.org/docs/en/latest/guide/overview/index.html.

Since a hybrid mobile application is developed using standard web technologies, the same code can be reused across the supported platforms (such as Android, iOS and Windows). Apache Cordova provides tools that enable you to add support for the platforms that the application will run on independent of this code.

JET uses Apache Cordova to develop web technology-based applications for some of the mobile platforms supported by Apache Cordova. So, one could say that the JET hybrid mobile application that you develop is an Apache Cordova application where JET provides features such as components and themes that determine the look and feel of your application.

A plugin is a package of code that allows the Cordova web view within which your application renders to communicate with the native platform on which it runs. The plugin does this by providing a JavaScript interface to native components that allows your application to use native device capabilities, such as camera, geolocation, and so on.

So, assume for example, that you want your application to use a camera. In that case, you look for an existing plugin to provide access to the camera on the platform(s) where your application will be installed as there is a good possibility that someone has already developed a plugin to address this requirement.

If you cannot find a plugin that meets your requirements, you can develop your own plugin. Although this blog post makes reference to another mobile development framework (MAF), it provides a suitable introduction to creating a Cordova plugin that could be used in a JET application or any Cordova-based application.

To find a plugin to use in your application, go to the Plugins page at https://cordova.apache.org/plugins/ that provides a registry of core and third-party Cordova plugins. Core plugins are plugins provided by Apache Cordova while third-party plugins are those developed by independent developers. Core plugins display a blue vertical strip to the left of the card that describes the plugin, as shown in the following figure, where two core plugins (cordova-plugin-media and cordova-plugin-contacts) appear after a third-party plugin named cordova-plugin-ble-peripheral.

The surrounding text describes the image.

The Plugins page categorizes plugins according to the platform on which the plugins will run. Some plugins run on a wide variety of mobile platforms (Android, iOS, Windows, and so on) while other plugins may only support one platform. Ensure that the plugins you install in your application support the platforms where your application will run.

Each entry generally provides information such as a brief description of the plugin’s functionality, the platforms it supports, and the number of days since it was updated. It then links to a web page where you can access more detail, such as how to install the plugin in your application and use it once installed.

Using a Plugin in Your App

You add the plugin and then write code that invokes the plugin’s JavaScript interface to access the device APIs.

To add a plugin to your app, change to the application’s root directory and use the ojet add plugin command. The following example illustrates how you install the phonegap-plugin-barcodescanner plugin.

ojet add plugin phonegap-plugin-barcodescanner

Once you have added the plugin to your app, you need to write code in your app to use the plugin. The following code excerpts illustrate how you might use the phonegap-plugin-barcodescanner plugin by exposing a button in the appRootDir/src/js/views/incidents.html page of a JET app built using the navbar template that invokes the barcode scanner on the device.

...
<oj-button id='b1Scan' on-click='{{buttonClick}}' label='Scan'></oj-button>
...

The following code excerpt shows the entries to add to the appRootDir/src/js/viewModels/incidents.js file which invokes the barcode scanner when an end user clicks the button that the incidents.html page renders.

self.buttonClick = function(data, event){
      cordova.plugins.barcodeScanner.scan(
          function (result) {
              alert("We got a barcode\n" +
                    "Result: " + result.text + "\n" +
                    "Format: " + result.format + "\n" +
                    "Cancelled: " + result.cancelled);
          },
          function (error) {
              alert("Scanning failed: " + error);
          }
      );
    }

Cordova Plugins Recommended by Oracle JET

JET recommends a number of Cordova plugins that you can use in your app to provide native device functionality.

The Cordova Plugins page on the Oracle JET web site lists a number of plugins that have been successfully used in the verification testing of JET sample or demo apps. Although Oracle JET recommends these plugins, it does not support them.

Using a Different Web View in your JET Hybrid Mobile App

JET hybrid mobile apps use the default web view supplied by each mobile operating system.

On the Android platform, this is the Android platform’s WebView. A number of Cordova plugins exist that enable you to use a different web view in your hybrid mobile app. One example for the Android platform is the cordova-plugin-crosswalk-webview plugin that configures your app to use the Crosswalk web view to bring performance improvements and compatibility improvements across older Android versions. Install this plugin in your app using the following command:

ojet add plugin cordova-plugin-crosswalk-webview

For more information about the cordova-plugin-crosswalk-webview plugin, read its documentation.

For apps that run on the iOS platform, consider adding the cordova-plugin-wkwebview-file-xhr plugin to your app so that your app uses the more performant WKWebView instead of the default UIWebView used on iOS devices.

ojet add plugin cordova-plugin-wkwebview-file-xhr

For more information about the cordova-plugin-wkwebview-file-xhr plugin, read its documentation.

Using the Native Platform’s Date Picker UI in your JET Hybrid Mobile App

Include the cordova-plugin-datepicker plugin in your JET hybrid mobile app if you want to present end users with the date picker UI of the underlying platform (Android, iOS, or Windows) when your app renders JET date or time components such as oj-input-date or oj-input-date-time.

JET hybrid mobile apps that do not include the cordova-plugin-datepicker plugin render the aforementioned JET components using the default UI provided by Oracle JET.

Install the cordova-plugin-datepicker plugin in your app using the following command:

ojet add plugin cordova-plugin-datepicker

For more information about the cordova-plugin-datepicker plugin, read its documentation.