iOS - Adding native UI elements
While writing hybrid application can be done by using solely web technologies, IBM MobileFirst Platform Foundation also allows to mix & match native code with web code as needed.
For example, use native UI controls, use native elements, provide an animated native introduction screen, etc. In order to do so, taking control of part of the application startup flow is needed. This tutorial assumes working knowledge of native iOS development.
Taking control of the startup flow
When creating a new hybrid application, MobileFirst Studio generates an App Delegate (YourAppName.m) that handles various stages of the application startup flow.
showSplashScreen method is called to display a simple splash screen while resources are being loaded. This is the location that can be modified with any native introduction screen.
initializeWebFrameworkWithDelegate method loads the resources that the web view needs to work correctly.
As soon as the web framework initialization finishes, the
wlInitWebFrameworkDidCompleteWithResult method is called.
At this point, by default, the application is still displaying the splash screen and no web view is being displayed yet.
The implementation can be modified to handle more of the status codes that are returned by the framework.
By default, a successful load calls the
A Cordova web view controller (
CDVViewController class) is initialized and the start page of the application is set.
The Cordova controller is then added as a child to the root view and displayed on the screen.
If it is decided to implement a custom introduction screen as explained before, consider delaying the display the Cordova view until the user is done with the custom native screen.
Native SplashScreen sample
The NativeUIInHybrid project includes a hybrid application called NativeSplashScreen.
This example uses a Page View Controller to show a sliding introduction to the application. The user interface was created using a Storyboard in XCode.
PageContentViewController, were created to handle the slides.
MyAppDelegate.didFinishLaunchingWithOptions method, the window is initialized and the PageViewController instance is set as the root of the window.
initializeWebFrameworkWithDelegate method is called from within the
This method initializes the MobileFirst framework in the background and calls the
wlInitWebFrameworkDidCompleteWithResult method once the framework is initialized.
wlInitWebFrameworkDidCompleteWithResult, method, different scenarios handled depending on the statusCode value of the
In this sample, only the common case of the
WLWebFrameworkInitResultSuccess value is modified.
wlInitDidCompleteSuccessfully, a Cordova controller is being prepared but is not displayed yet.
In this sample, the
PageViewController instance ends with a button that triggers a custom method called
onSplashScreenDone in the AppDelegate.
onSplashScreen custom method resumes where the flow was interrupted and displays the previously initialized Cordova view.
This feature can be used to trigger native code to be run in the background, to update the native UI, to use native-only features, etc.
doSomething is an arbitrary action name to be used in the native side (see the next step), and the second parameter is a JSON object that contains any data.
The native class to receive the action must implement the
WLActionReceiver protocol requires an
onActionReceived method in which the action name can be checked for and perform any native code that the action needs:
For the action receiver to receive actions from the MobileFirst Web View, it must be registered. The registration can be done during the startup flow of the application to catch any actions early enough:
This feature can be used to receive responses from a native method, notify the web view when background code finished running, have a native UI control the content of the web view, etc.
In Objective-C, the following API is used:
NSDictionary object that contains any data.
The first parameter is an arbitrary name. It can be used later to remove an action receiver.
Download the NativeUIInHybrid project, which includes a hybrid application called SendAction.
Note: This sample requires the MapKit framework.
This sample divides the screen in two parts.
- The top half is a Cordova web view with a form to enter a street address
- The bottom half is a native map view that shows the entered location if it is valid
If the address is invalid, the native map forwards the error to the web view, which displays it.
The HTML page shows the following elements:
- A simple input field to enter an address
- A button to trigger validation
- An empty line to show potential error messages
When the button is clicked, the
sendActionToNative method is called to send the address to the native code.
The code also registers an action receiver to display potential error messages from the native code.
The interface was designed with a Storyboard file. It features a generic view controller with the
ViewController custom class (described later).
The view controller contains a
MKMapView object and a Container View.
The Container View contains a view controller, which is set to use the
HybridScreenViewController class (described later).
CDVViewController, the Cordova web view provided by MobileFirst (
@interface HybridScreenViewController : CDVViewController).
The implementation of the class is almost empty, except for setting the startPage of the Cordova web view.
ViewController class extends
- Contains a reference to the
MKMapViewobject as a property
- Adheres to the
MKMapViewDelegateprotocol to receive updates about the map
- Adheres to the
WLActionReceiverprotocol to receive actions from the MobileFirst web view
- Contains a reference to a
CLGeocoderobject to enable geocoding addresses
The title of the controller is set to be displayed as part of a
The geocoder is initialized.
The map delegate is set.
ViewController is registered as an action receiver for MobileFirst.
onActionReceived method is called when the user submits the form. The action name is checked and the entered address is retrieved.
The geocoder is given the address.
If a location is found, the region is centered and a new
MKPlacemark is added to the map
If the search fails or no location is found, the
sendActionToJS method is called to transmit the error to the web view.
didFinishLaunchingWithOptionsmethod of the app delegate is generated by MobileFirst Studio and is left unchanged in this example
wlInitDidCompleteSuccessfullystatus code is modified to load the
ViewControllerobject from the Storyboard instead of loading the
HTTP requests are explained in other tutorials (both for hybrid and native applications).
Click to download the Studio project.▲