Getting Started with Kapsel - Part 12 -- Application Preferences (New in SP04)

[Dan_vL]

Application Preferences (New in SP04)

This plugin provides a native settings page for an app.  The settings screen can be shown by calling

sap.AppPreferences.showPreferencesScreen(successCallback, errorCallback);

In versions prior to SP05 SDK PL03, the showPreferenceScreen method only supported Android.  On iOS, the user had to go to the iOS settings screen to view the settings.  It now works for Android and iOS.

The settings are specified by calling

sap.AppPreferences.configurePreferencesScreen(preferencesJSON, successCallback, errorCallback);

where preferencesJSON describes the settings to be shown.

On Android, the settings values can be validated by including JavaScript code in a validation.html file as shown in the example below.  On iOS, the values can be validated via the regex field in the JSON.

The values can be accessed and modified programmatically by calling

sap.AppPreferences.getPreferenceValue(key, successCallback, errorCallback);

and

sap.AppPreferences.setPreferenceValue(key, value, successCallback, errorCallback);

For additional details on the apppreferences plugin see the JavaScript file in a project that includes this plugin at

project_name\plugins\com.sap.mp.cordova.plugins.apppreferences\www\apppreferences.js

or the JS Documentation at Kapsel Application Preferences API Reference.

The following steps will demonstrate an example of using this plugin.

• Create the project.

  cordova -d create C:\Kapsel_Projects\AppPreferencesDemo com.mycompany.apppreferences AppPreferencesDemo "{\"plugin_search_path\":\"C:/SAP/MobileSDK3/KapselSDK/plugins/\"}"
  
  cd C:\Kapsel_Projects\AppPreferencesDemo
  
  cordova -d platform add android
  
  
  
  cordova -d create ~/Documents/Kapsel_Projects/AppPreferencesDemo com.mycompany.apppreferences AppPreferencesDemo "{\"plugin_search_path\":\"/Users/i826567/SAP/MobileSDK3/KapselSDK/plugins/\"}"
  
  cd ~/Documents/Kapsel_Projects/AppPreferencesDemo
  
  cordova -d platform add ios

• Add the apppreferences plugin.

  cordova -d plugin add com.sap.mp.cordova.plugins.apppreferences
  
  

• Replace www\index.html with the contents of index.html.
  
  Note (Android specific), save the file validation.html to www\validation.html.  If the setting webapppath in the preferencesJSON is incorrect, the validation function will not work.
  
  
• Copy the files to the platform directory by running

  cordova -d prepare

• On Android, optionally choose a different theme for the settings dialog by modifying AndroidManifest.xml and changing minSdkVersion to 11 and the theme for PrefsActivity from Theme.Black.NoTitleBar to Theme.Holo.Light.  See also Android Themes.
  
  
• This step applies only if you are using a version of the plugin that is prior to SP05 PL03 on iOS.  On iOS, using versions prior to SP05 PL03 of the SDK, the preferences are specified by values in a plist file.  There is a sample one available at
  

  C:\SAP\MobileSDK3\KapselSDK\apps\fiori_client\assets\Root.plist

  In Xcode, right-click on AppPreferencesDemo > Resources > Settings.bundle > Root.plist and choose Open As > Source Code.  Copy the contents from the Fiori client sample Root.plist.  See also Settings Application Schema Reference.
  
  
• Use the Android IDE or Xcode to deploy and run the project.
  
  
  Note, in addition to the four types which are edittext, switch, checkbox and list there is also a button type that when pressed simply triggers the validation function on Android.
  
  On Android, if an alert() call is made following the call to sap.AppPreferences.showPreferencesScreen or in the successcallback method, the validation function will not be called in versions of Android less than 4.4.  A workaround for this is to add the plugin org.apache.cordova.dialogs and then to use navigator.notification.alert() instead of alert().
  
  
• Note that as of SP05 PL03 of the SDK, boolean values can no longer have quotes around them.  For example

  "defaultvalue" : "true"

  must be changed to

  "defaultvalue" : true

  
  There are a number of issues with the iOS version of this plugin in SP05 PL03 and SP06.  Because of this, consider using a previous version of this plugin.  The following are some of the issues seen while working with the above sample.
  BCP 1482004286.  On iOS, each setting must have a category.
  BCP 1482005324.  Missing support for switch and checkbox on iOS.
  BCP 1482005323.  Readonly attribute does not appear to work with a list type on Android or iOS.
  BCP 1482005322.  Defaultvalue attribute does not work for edittext types on iOS.
  
  

Back to Getting Started With Kapsel