Application Development

Custom Preference Screens

Build and integrate a custom preference screen for configuring local on-device user preferences.

By Frank Nimphius

January/February 2016

On-device mobile applications typically implement default values for basic application configuration settings, such as color schemes or default application behavior. Some settings, such as license keys and user account information for connecting to a server, cannot have default values, however. These settings are presented to (and must be set by) users the first time they run an application. Depending on the mobile device operation system, configuration settings are provided while the application is on (Android) or when it is off (iOS).

Applications created with Oracle Mobile Application Framework can implement this same type of behavior. This article explains how to create and invoke a custom user-preference page that resides within the mobile application (in-app) for configuring and editing a mobile app’s preference settings. Customizing in-app preferences enables developers to ensure consistency across mobile platforms, add branding, use graphics or maps in preference settings, and provide context-sensitive help for the preferences option.

Sample Application Overview

The sample application for this hands-on article is a simplified version of the amx:flexLayout component demo, available in the PublicSamples package that ships with the Oracle Mobile Application Framework extension.

As shown in Figure 1, the sample’s in-app configuration screen displays color areas whose layout and visibility can be controlled by the application’s preference configurations. The firstname and lastname fields in the application configuration simulate mandatory user entries (such as license key and account information).


Figure 1. Oracle Mobile Application Framework sample application

This configuration screen displays on application startup, when the firstname and lastname fields have no values, or at runtime when users tap the Edit Preferences link at the top of the sample page.

Application Preferences

Local application preferences are saved on a mobile device by an application for later read—when the application is stopped and then restarted, for example. Some applications use globally shared preferences, available across devices and mobile platforms for an authenticated user. At application startup, shared preferences are queried from a remote service and then saved to the local device for use when the application runs in offline mode. Both local and global preferences can be implemented with Oracle Mobile Application Framework AMX (Application Mobile XML), using Java in a managed bean or in an AMX data control.

Application preferences in Oracle Mobile Application Framework can be configured at the application level (maf-application.xml) or at the feature level (maf-feature.xml). As discussed in “Thanks for Sharing” (Oracle Magazine, Nov/Dec 2014), features in Oracle Mobile Application Framework are reusable modules that present a mobile task or use case within a mobile application. Defining application preferences at the feature level means they are reusable and will be automatically available to the application preferences of the consuming application.

Following the hands-on instructions in this article, you’ll define Oracle Mobile Application Framework feature-level application preferences and then set their values from an in-app configuration screen.

Getting Ready

Ensure that you’re using the studio edition of Oracle JDeveloper 12c (12.1.3) with the Oracle Mobile Application Framework (MAF) v2.2 extension, available as a free download on Oracle Technology Network.

In addition, follow the instructions in the Oracle Mobile Application Framework documentation to configure a Mac with Xcode or a Windows PC with the Android SDK (you’ll need an iOS simulator or an Android emulator for deploying and testing the sample).

Download the sample application, and unzip the file to a local folder on your computer. Do not use spaces in the folder name. For this application, you’ll use the starter folder from the download:

  1. In Oracle JDeveloper, select File -> Open and navigate to the folder containing the unpacked zip file content.
  2. Open the omag010216 -> starter folder, and select the oramag01022016.jws workspace file. Click Open to load the workspace.

Defining User Preferences

First you will define the local application preferences to be configured on the simulator or the emulator (or the physical device) upon Oracle Mobile Application Framework application deployment.

Note that this sample application uses many prebuilt artifacts to save you from having to write any code, but that means that you must be especially careful to use the names for preference groups and attributes exactly as defined in each step.

  1. Expand the ViewController project folder, then Application Sources, and then the META-INF folder.
  2. Right-click maf-feature.xml, and choose Open from the menu. The three features defined in the sample application display in the main editor window in the Features table on the Features tab. In the Features table, click the SampleMain feature, and then select the Preferences tab to open the preferences for this feature.
  3. Click the green plus (+) icon to open the Insert Preference Group dialog box, and provide the following values for each field: Id: user
    Label: User Data
  4. Click OK to create the preference group.
  5. Click the green plus (+) icon again, select Insert After Preference Group -> Preference Group, and enter the following values: Id: layout
    Label: Color Area Component Layout
  6. Click OK.
  7. Repeat steps 7 and 8, using these values:
    Id: display
    Label: Show / Hide Main Color Areas
  8. Right-click Preference Group – User Data, and choose Insert Inside Preference Group -> Text Preference. In the Insert Text Preference dialog box, enter these values: Id: firstname
    Label: First Name
  9. Click OK.
  10. Repeat steps 10 and 11, using these values: Id: lastname
    Label: Last Name
  11. Right-click Preference Group – Color Area Component Layout, and choose Insert Inside Preference Group -> Preference List from the menu. In the Insert Preference List dialog box, enter these values: Id: layoutOrientation
    Label: Parent Layout Orientation
  12. Click OK.
  13. Select the Preference List – Parent Layout Orientation preference item.
  14. In the Preference Value table, click the green plus (+) icon. In the Insert Preference Value dialog box, enter these values: Name: Vertical
    Value: vertical
  15. Click OK.
  16. Repeat steps 16 and 17 to define a list entry with these values: Name: Horizontal
    Value: horizontal
  17. Select the Preference List – Parent Layout Orientation entry to display Preference Values, and set Default to vertical.
  18. Right-click Preference Group – Color Area Component Layout, and choose Insert Inside Preference Group -> Preference List from the menu. In the Insert Preference List dialog box, enter these values: Id: childLayoutOrientation
    Label: Child Item Layout Orientation
  19. Repeat steps 15 through 20 for the Preference List – Child Item Layout Orientation entry.
  20. Save your work.
  21. Right-click Show / Hide Main Color Areas, and choose Insert Inside Preference Group -> Boolean Preference from the menu. In the Insert Boolean Preference dialog box, enter these values: Id: p1Rendered
    Label: Render Color Area 1
  22. Click OK.
  23. Select true from the drop-down list for this preference’s Default value.
  24. Repeat steps 23 through 25 to create the following preferences: Id value Label value
    p2Rendered Render Color Area 2
    fl2RenderedRender Color Area 3
    p3Rendered Render Color Child 1
    p4Rendered Render Color Child 2
  25. Save your work.
  26. Close all opened tab windows.

What you just did: You created text, list, and Boolean preferences for the Oracle Mobile Application Framework sample application’s SampleMain feature. At runtime, Oracle Mobile Application Framework applications access preferences by using expression language (EL) referenced from an AMX page or from Java. An EL preference address is constructed as follows:

#{preferenceScope.<feature | application>.<groupId>.<preferenceId>}. 

For example, to access the p1Rendered preference (for hiding/showing the first color area on the sample main page), the unique EL address is #{preferenceScope.feature.display.p1Rendered}.

If preferences were defined at the application level (in maf-application.xml), then the application string would replace the feature string. Preferences (the Id values) in Oracle Mobile Application Framework must be unique within each preference group, and each preference group ID must be unique in the scope of a feature or an application.

In the hands-on sample, the preference groups and items you just created are referenced on the predefined sampleMain.amx and userPreferences.amx pages and by the class that is exposed as a managed bean.

Building the Navigation Flow

This sample application aims to meet two mobile requirements: providing an in-app page that enables users to configure application preferences without leaving the application, and automatically showing this page when users launch the application prior to having set up required configuration settings. You’ll implement this behavior by defining the Oracle Mobile Application Framework AMX task flow for the SampleMain feature with the following task flow artifacts:

  • Task flow control flow cases that allow navigation to the preference view
  • A router activity to handle the initial navigation when users enter the feature
  • View activities to display the preference and the sample main screen
  • A managed bean containing the logic that displays the preference page on application start as needed
  1. In Oracle JDeveloper, back in the Project pane of the Application Navigator, expand the View Controller folder, then the Web Content folder, and finally the oramag.maf.sample.SampleMain folder.
  2. Right-click sample-main-flow.xml, and choose Open from the menu.
  3. Click the Diagram tab at the bottom of the task flow window if necessary to activate the Bounded Task Flow page. (If necessary, select Window -> Properties and then Window -> Components from the Oracle JDeveloper menu to open the Property Inspector and the Components palette, respectively.)
  4. In the Components palette (Components category, in the Activities section), click Router and then click anywhere in the task flow diagram to create a router instance, and rename it initialPageView.
  5. In the Components palette, click View and then click anywhere in the task flow diagram and rename the view activity sampleMain.
  6. Repeat step 33 to create a view activity named preferenceScreen.
  7. Now you can connect the router and activities by using control flow cases. In the Control Flow subsection of the Components palette, click Control Flow Case, then (in the task flow diagram) initialPageView router activity, and then sampleMain view activity. Name the navigation flow line gotoSample, ignoring the yellow warning that displays when you finish.
  8. Repeat step 35 to create control flow cases using the following directions and names: From To Flow name
    sampleMain preferenceScreeneditPreferences
    preferenceScreeninitialPageView validatePreferences
  9. When you’re finished, the task flow diagram should look like the one in Figure 2.


    Figure 2. Task flow diagram with activities and router connected but not complete
  10. In the task flow diagram, click the sampleMain view activity. The sample page has been precreated, and you can now associate it with the sampleMain view activity. In the Properties pane for the sampleMain view, hover the cursor near the far right of the Page field to display the cog icon.
  11. Click the cog icon, and then double-click sample to open the folder. In the open sample folder, select sampleMain.amx and click OK.
  12. Repeat steps 38 and 39 for the preferenceScreen view activity, but select the userPreferences.amx page.

Note: Both sampleMain.amx and Preferences.amx use EL on the AMX user interface components to reference the user preferences you created in the maf-preference.xml file. (To understand how these work, I suggest looking at the source code for these files in Oracle JDeveloper.)

  1. Before you can configure the router activity, you must configure the managed bean it will use to specify which page initially displays. To do so, click the Overview tab at the bottom of the task flow editor.
  2. From the left-hand menu, select Managed Beans.
  3. Click the green plus (+) icon in the Managed Beans header, and then enter preferenceRouter in the Name field.
  4. On the same entry row, click in the Class field. Start typing the word Preference, and then select PreferenceRouterBean from the code-completion menu to set as the class.
  5. Ensure that the Scope value is set to view.
  6. Save your work, and then click the Diagram tab at the bottom of the overview dialog box.
  7. In the task flow diagram, click the initialPageView router activity to activate its Properties pane, and choose editPreferences (from the selector list) for the Default Outcome property.
  8. In the Cases section, click the green plus (+) icon to define the case (logic) that will be used at runtime to evaluate which page to display.
  9. In the Expression field (or using the Expression Builder, selected from the drop-down menu at the end of the field), type the following string:
  10. Set the Outcome field to gotoSample.
  11. Repeat steps 48 through 50, but set the Expression field value to #{!viewScope.preferenceRouter.hasRequiredPreferencesSet} and the Outcome field value to editPreferences.
  12. Save your work.

What you just did: You’ve created the navigation flow that enables users to tap on a command link to access application preferences from the sample main page. You’ve also created a router activity that opens preferences at application startup, but only if required settings are missing. The router activity references the class implemented in to evaluate the settings. I recommend looking closely at the Java code to learn how to use EL in Java to access Oracle Mobile Application Framework application preferences.

Starting the Sample for a Test

Because this sample includes most of the code, you can now run and test the application.

  1. From the Oracle JDeveloper menu, select Run -> Choose Active Run Configuration and the run target (iOS Simulator or Android Emulator). (Note that on-device testing requires you to create a deployable package from the Application -> Deploy menu and that other details are not covered in this article.)
  2. Right-click the ViewController project, and choose Run from the menu.

Testing the Sample
  1. When the application starts, you’ll see an About page and a description of the Oracle Magazine Sample. Tap the hamburger icon to open the menu.
  2. The first time you run the application, the in-app user preference screen appears and you can enter values for the required firstname and lastname fields. After entering values for these fields, tap the Run Sample Page command link on top to see the sample page.
  3. Use the Edit Preferences link to navigate back to the in-app preference screen and change the settings for the color areas in the UI.
  4. Stop the application, and then restart it. This time the user preference screen does not appear, because the required values (firstname and lastname) now exist.

Figure 3 shows the user preference settings as they appear on the iOS platform. Changes made to preferences within the Oracle Mobile Application Framework application are automatically updated on the mobile device and are also automatically picked up by Oracle Mobile Application Framework.


Figure 3. User preferences on an iOS device


In this article, I showed how Oracle Mobile Application Framework application developers can build a reusable Oracle Mobile Application Framework feature-level in-app preference page that ensures a consistent application-specific look and feel for all application configuration requirements across mobile platforms and devices.

Next Steps

 READ more about Oracle Mobile Application Framework.

 EXPLORE Oracle Mobile Application Framework.


Photography by Panuwat Phimpha, Shutterstock