JBoss.orgCommunity Documentation
Apache Cordova is a framework for hybrid mobile application development. It simplifies mobile application development by enabling developers to use device-independent APIs, in place of native code, to access device functionality.
Cordova consists of plug-ins, each providing a wrapper API to gain access to corresponding native device APIs. Cordova APIs are available for a range of device functionality, including cameras, accelerometers, and filesystems. All of the Cordova APIs have a JavaScript interface and native backing code to support a variety of different device operating systems, including iOS and Android.
The JavaScript interface of Cordova APIs provides consistent methods for accessing native device functionality regardless of operating system. Applications using Cordova are written once and packaged using native software development kits (SDKs) to produce hybrid mobile applications.
Cordova applications have a distinctive project structure:
An essential config.xml file holds information about the application. It specifies features, preferences and access details that affect how the application works, for example whether the application responds to orientation changes.
An application is implemented as a web page. The default starting page is index.html and device-independent resources are stored in a www directory.
An application must reference the cordova.js file, which holds necessary API bindings that enable the application to interact with device features.
Apache Cordova is an open source project, of which there are various distributions. PhoneGap, in addition to being the originator of Cordova, and IBM Worklight are such distributions.
Hybrid Mobile Tools provides tooling for developing Cordova-based hybrid mobile applications within the IDE. It simplifies the process of getting started with the Cordova technology that can be used for these types of applications and provides workflows for developing Cordova-based hybrid mobile applications.
Hybrid Mobile Tools consists of the Apache Cordova API and wizards, a dedicated editor and actions for developing Cordova-based hybrid mobile applications for iOS and Android operating systems:
The included Apache Cordova API is version 3.0.x.
The Hybrid Mobile Application project wizard creates a sample project to demonstrate the Cordova project structure and provides you with a template from which to create your own applications.
The Cordova Configuration Editor offers simplified management of config.xml files, with dedicated panes for adding and editing project descriptions, features, preferences and access. An additional pane enables direct editing of config.xml files.
The Cordova Plug-in Discovery wizard assists you to add Cordova plug-ins to your projects. Plug-ins can be installed from the Cordova registry, Git and directories. Information displayed in the Project Explorer tab is extended to show installed plug-ins and enable their management.
Actions are provided for calling external Android and iOS SKDs to package Cordova-based hybrid mobile projects into native applications and subsequently run them on their associated simulators or connected Android devices.
Export wizards are available for exporting Cordova-based hybrid mobile projects from the IDE workspace as Cordova-enabled iOS or Android projects and ready-to-sign applications.
Hybrid Mobile Tools, together with CordovaSim, provides an effective hybrid mobile development and testing environment.
CordovaSim is a mobile application simulator. It enables you to view and test Cordova-based hybrid mobile applications through a mobile device simulator.
CordovaSim consists of a device input panel based on an extended version of Apache Ripple, teamed with BrowserSim. The input panel provides the ability to give sample input for device features to the application, such as camera, geolocation and accelerometer data. BrowserSim displays and enables user interaction with the application.
Extensions to the device input panel for CordovaSim include the following:
CordovaSim supports a range of Cordova API implementations: the core Apache Cordova 3.0.x plug-ins, several PhoneGap plug-ins and custom plug-ins. Supported PhoneGap plug-ins include BarcodeScanner and ChildBrowser. (Note that exceptions to the supported core Apache Cordova plug-ins are File and the captureAudio and captureVideo methods of Capture.)
CordovaSim automatically injects an up-to-date version of the cordova.js library into your project code at simulation time in the case that it is missing. Typically this file is added when a project is built with a native SDK. This response by CordovaSim enables it to simulate applications of Cordova-based hybrid mobile projects and Cordova-enabled Android projects without requiring native SDKs.
The use of BrowserSim for displaying the application extends the functionality of the mobile application simulator to encompass all of the BrowserSim functionality. This functionality includes skins, screen captures and LiveReload.
The overall system requirements of JBoss Tools are applicable for Hybrid Mobile Tools and can be viewed at https://community.jboss.org/wiki/MatrixOfSupportedPlatformsRuntimesAndTechnologiesInJBossToolsJBDS on the JBoss Tools website. But, as reiterated below, there are additional system requirements and restrictions when using Hybrid Mobile Tools.
Hybrid Mobile Tools actions involving iOS and Android require the associated SDKs to be installed on your system.
CordovaSim is a standalone simulator for mobile device operating systems, including iOS and Android. It does not require native SDKs to be installed in order to simulate successfully.
This is available as part of Apple XCode. For further information see https://developer.apple.com/xcode/ on the Apple website.
This is available as part of Android Development Tools. For further information see http://developer.android.com/sdk/index.html on the Android Developers website. Note that for Android actions in Hybrid Mobile Tools it is only necessary to install the Android SDK, which includes the Android Emulator.
Once downloaded, you must use the included Android SDK Manager to further download necessary APIs and set up Android virtual devices (AVDs).
Once the Android SDK is installed, you need to inform the IDE of its location. In the IDE, click → and select Hybrid Mobile. In the Android SDK Directory field, type the path of the installed SDK or click to navigate to the location. Click and click to close the Preferences window.
The overall system requirements of JBoss Tools are applicable for CordovaSim and can be viewed at https://community.jboss.org/wiki/MatrixOfSupportedPlatformsRuntimesAndTechnologiesInJBossToolsJBDS on the JBoss Tools website. But CordovaSim uses BrowserSim and, as reiterated below, there are additional system requirements and restrictions when using BrowserSim on Microsoft Windows operating systems.
BrowserSim depends on WebKit and, consequently, requires Apple Safari to be installed on Microsoft Windows operating systems. Only a 32-bit version of Apple Safari is available for Microsoft Windows operating systems. To work around this restriction for 64-bit Microsoft Windows operating systems, you must set BrowserSim to use a 32-bit JVM when running in 64-bit versions of Eclipse. Note that 32-bit JVM choice is limited to Oracle 32-bit JRE 1.6, JDK 1.6, or JDK 1.7 on Microsoft Windows operating systems because Oracle 32-bit JRE 1.7 is incompatible with Apple Safari.
To set BrowserSim to use a 32-bit JVM, click →. Expand JBoss Tools and select BrowserSim/CordovaSim. Under Select JRE to run BrowserSim, click Select and from the list select a 32-bit JRE or Java developer kit. Click and click to close the window.
Hybrid Mobile Tools and CordovaSim are not packaged as part of JBoss Tools installations. These plug-ins must be installed independently through JBoss Central.
To install these plug-ins, open the JBoss Central tab and select the Software/Update page. In the Find field, type JBoss Hybrid Mobile Tools + CordovaSim (Experimental) or scroll through the list to locate it. Select the corresponding check box and click .
In the Install wizard, ensure the check boxes are selected for the software you want to install and click . It is recommended that you install both the Hybrid Mobile Tools and CordovaSim components.
Review the details of the items listed for install and click . After reading and agreeing to the license(s), click I accept the terms of the license agreement(s) and click . The Installing Software window opens and reports the progress of the installation.
During the installation process you may receive warnings about installing unsigned content. If this is the case, check the details of the content and if satisfied click to continue with the installation.
Once installing is complete, you are prompted to restart the IDE. Click to restart now and if you need to save any unsaved changes to open projects. Note that changes do not take effect until the IDE is restarted.
The aim of this section is to guide you in using Hybrid Mobile Tools and CordovaSim:
Create the basis of new hybrid mobile projects using the project wizard
Add and remove Cordova plug-ins from your applications
Manage the Cordova functionality of applications using the Cordova Configuration Editor
Run and test hybrid mobile applications with CordovaSim or call external Android and iOS SDKs to run applications on their associated simulators and, in the case of Android, attached devices
Customize the settings used by CordovaSim, Android and iOS simulators for running hybrid mobile applications
Export workspace applications as Cordova-enabled native projects or ready-to-sign applications
A project wizard is available to assist you in generating new hybrid mobile applications, as demonstrated in the procedure below. It creates a Cordova project with structure compatible with projects generated by the Cordova command-line interface (CLI).
Procedure 7.1. Create a Hybrid Mobile Project
Click →→.
Expand Mobile, select Hybrid Mobile (Cordova) Application Project and click .
Complete the following fields:
In the Project name field, type a name for the project. This value is the name of the directory to be created and in which the source files for the application are stored, for example My_App.
In the Name field, type a name by which the hybrid mobile application is to be known. This value is the display text used to represent the application in listings and device home screens, for example My Application.
In the ID field, type an ID for the hybrid mobile application. The value is typically a reverse domain-style identifier, for example com.example.myapp, and for applications that are to be distributed through device platform application stores the ID value will be provided by the store.
There are restrictions on the ID you can use for an application. IDs must consist only of alphanumeric characters and dots. IDs must begin with an alpha character and contain at least one dot.
By default, the project is created in a subdirectory of the workspace that is named according to the project name. To change the default location, clear the Use default location check box. From the Choose file system list, select the default or RSE (Remote System Explorer) as appropriate. In the Location field, type the path where the project is to be created or click to navigate to the location.
To create the project, click .
During project creation, the wizard imports project dependencies and populates a config.xml file. Once created, the project is listed in the Project Explorer tab and the config.xml file is automatically opened in the Cordova Configuration Editor.
Plug-ins, or features, provide the application with access to the necessary Cordova APIs at runtime. Hybrid Mobile Tools provides actions for installed and removing plug-ins associated with applications, as detailed here.
In the Project Explorer tab, right-click the plugins folder and click .
The Cordova Plug-in Discovery wizard opens. The Cordova Plug-in Discovery wizard can install Cordova plug-ins from Cordova registries, git locations and system directories:
In the Registry tab, in the Find field enter the name of the feature or scroll through the list to find the plug-in. Select the check box for the plug-in and click . Check the details of the selected plug-in and use the drop-down list next to the plug-in name to select the version. Click .
In the Git tab, in the URL field type the URL that specifies the plug-in location. Click .
In the Directory tab, in the Directory field type the path of the plug-in or click to navigate to the location. Click .
After installing the plug-in, the config.xml file is automatically updated with the associated feature and param statements for the plug-in.
In the Project Explorer tab, in the plugins folder right-click the plug-in and click .
Alternatively, you can add and remove plug-ins by using the Platform Properties mode of the Cordova Configuration Editor.
The Cordova Configuration Editor is available for managing the settings of Cordova projects that are specified in the config.xml file. This editor has four modes: Overview, Platform Properties, Icons & Splash Screen, and config.xml. As described below, the first three modes provide interfaces for configuring the settings specified in the config.xml file and the fourth mode enables direct editing of the file.
The Overview mode details explanatory application information. Within this mode you can specify the name and description of the project, the content source of the application, and author details.
The Platform Properties mode specifies Cordova project functionality, such as features (plug-ins and parameters), preferences and access.
The Icon & Splash Screen mode lists the icon and splash screen images to be used on the various operating systems and resolutions for which the application is being developed.
The config.xml mode provides an editor in which to view and modify the config.xml file directly.
To open the Cordova Configuration Editor for a specific hybrid mobile project, in the Project Explorer tab right-click the config.xml file. Click Open With→Cordova Configuration Editor. All changes to the Cordova settings of a project must be saved before the results will take effect. To save, press Ctrl+S.
The Overview mode of the Cordova Configuration Editor enables you to edit the application information of a hybrid mobile project. Information pertains to the name, description and author of the application. More specifically, the Name and Description section details the application ID, name, version, description and content source or home page. The Author section holds author name, email and URL. All field values can be edited as detailed below.
Click the appropriate field and edit the content.
All changes to config.xml must be saved before the results will take effect. To save, press Ctrl+S.
The Platform Properties mode of the Cordova Configuration Editor enables you to specify the Cordova settings in your hybrid mobile project. Features, parameters, preferences and access can be added and removed as detailed below.
Features are the Cordova API plug-ins required by the application in order to access native APIs at runtime. Examples include Camera, Contacts and Geolocation.
To add a feature, click for the Features table. The Cordova Plug-in Discovery wizard opens. Follow the instructions as appropriate for the plug-in source:
For the Cordova registry, click the Registry tab. In the Find field, enter the name of the feature or scroll through the list to find the plug-in. Select the check box for the plug-in and click . Check the details of the selected plug-in and use the drop-down list next to the plug-in to select the version.
For Git, click the Git tab. In the URL field, type the URL that specifies the plug-in location.
For a system directory, click the Directory tab. In the Directory field, type the path of the plug-in or click to navigate to the location.
To add the feature, click .
All parameters are associated with a feature and provide information about the specific mapping of Cordova and native APIs.
To add a parameter, from the Features table select an item for which to create a parameter. For the Params table, click . In the name and value fields, type the service name and Java class full name (including namespace), respectively. To add the parameter, click .
Preferences details the global, cross-platform and platform-specific behaviors for the web view of the hybrid mobile application.
To add a preference, click for the Preference table. Complete the name and value fields as appropriate. To add the parameter, click .
By default for an application created with the Hybrid Mobile Tools project wizard, the Preferences table has two entries. The fullscreen and webviewbounce elements specify whether the application is fullscreen and bounces when pulled down in iOS devices, respectively. For a full list of available preferences see http://cordova.apache.org/docs/en/edge/config_ref_index.md.html#The%20config.xml%20File on the Apache Cordova website.
Access entries specify the external network resources to which the application has access, also referred to as whitelisting.
To add an access entry, click for the Access table. In the required Origin field, type the URL to which access is granted, using * as a wildcard character. Select the Allow Subdomains and Browser Only check boxes as appropriate. These items enable access to subdomains and cause links to open in browsers rather than the application window, respectively. To add the access entry, click .
By default for an application created with the Hybrid Mobile Tools project wizard, the Access table has an entry allowing access to all networks, <access origin="*" />. You are advised to declare access to specific network resources.
In the appropriate table, select the item to be removed and click . Note that removing a feature also removes the associated parameters.
All changes to config.xml must be saved before the results will take effect. To save, press Ctrl+S.
The Icons & Splash Screen mode of the Cordova Configuration Editor enables you to control the icons and splash screen used by the application on each operating system. Icons are used as the visual representation of the application on different platforms and splash screens are used when the application starts on different platforms. In this mode, icons and splash screens can be added and removed as detailed below.
Click for the appropriate table. Locate the image within the www directory and click .
To set the display properties of an icon or splash screen, ensure the icon or splash screen image is selected in the table and edit the information in the appropriate Image Details pane:
The Width and Height pixel values determine the reproduced image size.
The Platform value identifies the operating systems for which the image is applied, for example ios or android.
The Density value specifies the Android device pixel density for which the image is applied, for example ldpi, mdpi, hdpi and xhdpi.
Each platform has different icon and splash screen image requirements, including location and size. For more information see http://cordova.apache.org/docs/en/edge/config_ref_images.md.html on the Apache Cordova documentation website.
In the appropriate table, select the icon or splash screen image to be removed and click .
All changes to config.xml must be saved before the results will take effect. To save, press Ctrl+S.
You can use the actions of Hybrid Mobile Tools to run applications on devices and simulators, as detailed below.
In the Project Explorer tab, right-click the project name and click →. This option calls the external Android SDK to package the workspace project and run it on an Android device if one is attached. Note that Android APIs and AVDs must be installed and the IDE correctly configured to use the Android SDK for this option to execute successfully.
In the Project Explorer tab, right-click the project name and click →. This option calls the external Android SDK to package the workspace project and run it on the Android emulator. Note that Android APIs and AVDs must be installed and the IDE correctly configured to use the Android SDK for this option to execute successfully.
This process fails if you have Android API level 12 or earlier installed on your system. For more information see https://issues.jboss.org/browse/JBIDE-15885 on the JBoss issue tracking website.
This option is only displayed when using OS X operating systems, for which iOS Simulator is available. For information about iOS Simulator see https://developer.apple.com/xcode/index.php on the Apple Developer website.
In the Project Explorer tab, right-click the project name and click →. This option calls the external iOS SDK to package the workspace project into an XCode project and run it on the iOS Simulator.
In the Project Explorer tab, right-click the project name and click →. This opens the application in CordovaSim, which is composed of a BrowserSim simulated device and a device input panel.
Run configurations inform simulators how to run the application associated with a project. Hybrid Mobile Tools generates a default run configuration for a project the first time it is run by a specific simulator. This default run configuration is simulator-specific and named according to the project name. You can create and customize multiple run configurations for your projects using the Run Configurations manager.
The information below details how to manage run configurations using the Run Configurations manger. To open the Run Configurations manger for a project, in the Project Explorer tab right-click the project name and click Run As→Run Configurations. Note that run configurations are organized by simulator within the Run Configurations manager, namely CordovaSim, Android and iOS Simulator.
From the list of run environments, right-click the simulator and click . Complete the fields as appropriate. To save the new run configuration, click .
From the list of run environments, expand the simulator. This shows a list of the run configurations associated with the simulator.
Details for a run configuration are organized in tabs. All simulators have the same Common tab. These options include where to save the run configuration information and how standard input and output are managed. Additional customizable options vary according to simulator:
For Android, you can specify details about the virtual device to be used by the emulator and the values of environment variables. Additionally, you can customize which of the information returned by the Android emulator is shown in the IDE console.
For CordovaSim, you can customize default values including the location of the root folder containing key device-independent files, the application start page opened when CordovaSim starts, and the server port used by CordovaSim to host the application.
To change the value of any variables listed in the tabs, click the appropriate field and edit the content. To save changes, click .
From the list of run environments, expand the simulator and select a run configuration. Click . This starts the simulator, which runs the application associated with the project using the specified configuration settings.
Hybrid Mobile Tools provides actions for exporting workspace projects from the IDE. Projects can be exported as native projects and ready-to-sign applications, as detailed in the procedure below.
Android and iOS APIs must be installed and the IDE correctly configured to use the Android SDK for this procedure to execute successfully.
Procedure 7.2. Export a Hybrid Mobile Project
In the Project Explorer tab, right-click the project name and click .
Expand Mobile, select the export type as appropriate and click :
To export as a native project, select Export Native Platform Project.
To export as an application, select Export Mobile Application.
Complete the following fields:
From the Select Projects list, select the check boxes of one or more workspace projects to be exported.
From the Select Platforms list, select the check boxes of one or more operating systems for which you want to export the selected project. Only operating systems with installed SDKs are listed.
In the Directory field, type the path to which the projects are to be exported or click to navigate to the location.
Click . The projects are exported to the provided location. Exported native projects are organized with subdirectories for each selected operating system.