12 Implementing Application Features as Remote URLs

This chapter describes how application features with content from remote URLs can access (or be restricted from) device services.

This chapter includes the following sections:

12.1 Overview of Remote URL Applications

By configuring the content type for an application feature in the overview editor for the adfmf-feature.xml file as Remote URL as described in Section 5.9.1, "How to Define the Application Content," you create a browser-based application that is served from the configured URL. Such server-hosted applications differ from applications written in ADF Mobile AMX or a platform-specific language such as Objective-C in two ways: they are intended for occasional use and cannot access the device memory or services directly, as these interactions are contingent upon the capabilities of the device browser.

Browser-based applications targeted for smartphones are authored with Apache Trinidad components (described at http://myfaces.apache.org/trinidad/) to enable proper rendering of a variety of feature phones and smartphones. An application that runs on a tablet can be created in the same manner as an ADF desktop web application.

Note:

Oracle recommends using ADF Mobile browser for application features that derive their content from remote URLs. ADF Mobile browser applications are comprised of JSF pages populated with Apache Trinidad components. For more information, see Oracle Fusion Middleware Mobile Browser Developer's Guide for Oracle Application Development Framework.

12.2 Overview of Enabling Remote URL Implementations to Access PhoneGap

By default, access to such device capabilities as contacts or GPS (Global Positioning Services) are restricted to ADF Mobile applications implemented as a bundle of locally stored HTML pages or as ADF Mobile AMX. In the case of the latter, you can enable the application feature to access device capabilities by adding device data controls to an ADF Mobile AMX UI component. For more information, see in Section 9.5, "Using the DeviceFeatures Data Control." Remote URL implementations, however, can only access device-native controls through PhoneGap JavaScript APIs. As described in Chapter 6, "Controlling the Display of Application Features," the ADF Mobile JavaScript file is the mechanism through which ADF Mobile interfaces with PhoneGap.

12.3 Enabling Remote Application to Access Device Services through Whitelists

ADF Mobile supports the concept of whitelists, a registry of URLs that open within the application web view and can access various device services, such as GPS, a camera, or a file system. If a web page is not included on a whitelist (that is, it is not whitelisted), the ADF Mobile PhoneGap implementation opens a web page in the device browser (such as Safari) instead. Without whitelisting, a remote web page cannot open within a web view.

By default, the domains defined in the connections.xml file, the repository for all of the connections defined in the ADF Mobile application, are whitelisted automatically. These connections are defined using the Create URL Connection dialog, shown in Figure 12-4. ADF Mobile parses the domain from each of the connection strings and adds these domains to the whitelist.

Figure 12-1 Creating the Connection to Retrieve the Content of the Remote URL Application Feature

Point to the application server URL.

JDeveloper then populates the connections.xml file, located in the Application Resources panel, with the connections information and also creates the connection resources, such as oracle and connection 1 in Figure 12-2.

Note:

Only whitelisted domains open in the web view; all other (non-whitelisted) domains open in the device browser.

12.3.1 How to Control Access to Device Capabilities

By editing the adfmf-application.xml file, shown in Figure 12-2, you can restrict access to the PhoneGap-enabled device services on a per-application feature basis. By default, all application features have such access, meaning that any whitelisted domain configured for the ADF Mobile application can also access the device. In addition to the domains that ADF Mobile includes from the connections.xml file, you can also whitelist domains using the Security page of the adfmf-application.xml file, as described in Section 12.3.2, "How to Create a Whitelist."

Figure 12-2 Editing <adfmf-FeatureReference> to Limit Domain Access

Edit allowDeviceAccess attribute.

The Source editor illustrated in Figure 12-2 shows the <adfmf-feature-reference> element populated with the allowDeviceAccess attribute. JDeveloper populates all application features with remote URL content with this attribute, which by default, is set to true. This default setting signifies that all URLs can access the PhoneGap APIs.

Before you begin:

Using the overview editor for the adfmf-feature.xml file (located in the Application Navigator in the Project panel under the View Controller and META-INF nodes), you must designate the content for an application as Remote URL and then create the connection as described in Section 5.5.1, "How to Designate the Content for a Mobile Application."

Open the overview editor for the adfmf-application.xml file by double-clicking the adfmf-application.xml file (located Application Resources panel under the Resources and ADF META-INF nodes, as shown in Figure 12-2).

You can use the Source editor, Structure Window, and the Properties editor to configure this attribute.

To restrict access to device services:

  1. Open the adfmf-application.xml file and then open the Feature References page.

  2. Using the dropdown menu from the Allow Device Access column of the Feature References table, change the default value (<default> true) to false, as shown in Figure 12-3.

    Figure 12-3 Preventing Domains from Accessing Device Services Using the Feature References Page

    Setting access to PhoneGap services.

12.3.2 How to Create a Whitelist

You configure the whitelist in the Security page of adfmf-application.xml, shown in Figure 12-4.

Figure 12-4 Configuring a Whitelist

Add whitelisted domains to the mobile application.

Before you begin:

Be aware that some URLs configured in the ADF Mobile application may open to other domains.

To create whitelists:

  1. Open the adfmf-application.xml file and then select the Security page.

  2. Click Add and then enter the domains that can be called from within the web view of the application feature. These domains can include a wildcard (*). For example, *.example.com is a valid domain entry as is *.example.*. You cannot enter a fully qualified path.

    Caution:

    Entering only the wildcard allows the web view to request all domains and can pose a security risk; adding all domains to the whitelist not only enables all of them to open within the web view, but also enables all of them to access the device (whether or not it is intended for them to do so).

12.3.3 What Happens When You Add Domains to a Whitelist

When you add a domain, JDeveloper updates <adfmf:remoteURLWhiteList> element as illustrated in Example 12-1.

Example 12-1 Configuring the Whitelist

...
<adfmf:remoteURLWhiteList>
  <adfmf:domain>*.oracle.*</adfmf:domain>
  <adfmf:domain>www.oracle.*</adfmf:domain>
  </adfmf:remoteURLWhiteList>
...

12.3.4 What You May Need to Know About Remote URLs

Some URLs are redirected to a URL that may not be part of the whitelist domain. These URLs may open in the device browser rather than the application web view. For example, if you whitelist www.oracle.com (<adfmf:domain>www.oracle.com<adfmf:domain>) and open that site on the device, ADF Mobile redirects to the mobile version of this site (www.oracle.mobi), because it does not pass the whitelist. Figure 12-5 shows a web page that has not been whitelisted and has opened within the device browser.

Figure 12-5 A Web Page Opening in the Device Browser, Not the ADF Mobile Web View

Content outside the web view.

To enable www.oracle.com to open within the application web view, you must specify *.oracle.* or www.oracle.* as shown in Example 12-1.

Because ADF Mobile whitelist is at the domain-level, you cannot restrict an individual page within a whitelisted domain from opening with an application feature web view; all pages are allowed.

12.4 Creating Whitelists for Application Components

Use a whitelist for pages that contain links to URLs that point to another domain. Such pages would otherwise open in the device browser instead of the ADF Mobile web view. In such a case, you can create an anchor tag or an <amx:goLink> component with a url attribute for the <amx:goLink> component that points outside of the application, such as the url attribute in <goLink2> in Example 12-2.

Example 12-2 <amx:goLink> with a url Parameter

<?xml version="1.0" encoding="UTF-8" ?>
<amx:view xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
          xmlns:amx="http://xmlns.oracle.com/adf/mf/amx"
          xmlns:dvtm="http://xmlns.oracle.com/adf/mf/amx/dvt">
  <amx:panelPage id="pp1">
    <amx:panelGroupLayout id="panelGroupLayout1">
      <amx:goLink text="This opens in the device browser"
                  id="golink1"
                  url="http://www.example.com"
                  shortDesc="Opens in device browser"/>
      <amx:goLink text="This opens in the web view"  
                  id="golink2"
                  url="http://www.example2.com"
                  shortDesc="Accesses device services"/>
    </amx:panelGroupLayout>
  </amx:panelPage>
</amx:view>

See also Section 8.3, "Creating and Using UI Components."

12.5 Enabling the Browser Navigation Bar on Remote URL Pages

ADF Mobile enables you to add a navigation bar with buttons for back, forward, and refresh actions for application features implemented as remotely served web content that open within the ADF Mobile web view, as shown in Figure 12-6. The forward and back buttons are disabled when either navigation forward or back is not possible.

Note:

The back button is disabled on Android-powered devices.

Figure 12-6 A Remote Web Page Displaying the Navigation and Refresh Buttons

Remote URL displays in the web view.

12.5.1 How to Add the Navigation Bar to a Remote URL Application Feature

You enable users to navigate through, or refresh remote content through the Content tab of the overview editor for the adfmf-feature.xml file.

Before you begin:

Designate an application feature's content be delivered from a remotely hosted application by first selecting Remote URL and then by creating the connection to the host server, as described in Section 5.9, "Defining the Content Types for an Application Feature."

Ensure that the domain is whitelisted.

To enable a navigation bar:

  1. Select the Remote URL application feature listed in the Features table in the adfmf-feature.xml file.

  2. Click Content.

  3. Select Show Browser Navigation Buttons, as shown in Figure 12-7.

    Figure 12-7 Selecting Navigation Options

    Select for navigation icons.

12.5.2 What Happens When You Enable the Browser Navigation Buttons for a Remote URL Application Feature

JDeveloper updates the adfmf:remoteURL element with an attribute called showNavButtons, which is set to true, as shown in Example 12-3.

Example 12-3 The showNavButtons Attribute

<?xml version="1.0" encoding="UTF-8" ?>
<adfmf:features xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                xmlns:adfmf="http://xmlns.oracle.com/adf/mf">
  <adfmf:feature id="oraclemobile" name="oraclemobile">
    <adfmf:content id="oraclemobile.1">
      <adfmf:remoteURL connection="connection1" 
                       showNavButtons="true"/>
    </adfmf:content>
  </adfmf:feature>
</adfmf:features>

After you deploy the application, ADF Mobile applies the forward, back, and refresh buttons to the web pages that are traversed from the home page of the Remote URL application feature, as shown in Figure 12-8.

Figure 12-8 Traversing Through a Remote URL Application Feature

Back, Forward, and Refresh button in deployed application.