Setting cookies using WL.Client.setCookie

MFP 7.0 introduced a new API, WL.Client.setCookie(), that allows us to set cookies that should be sent to hosts by subsequent AJAX calls.

Documentation is lacking, so here is an example that works:

WL.Client.setCookie({
  name: 'cookieName',
  value: 'cookieValue',
  domain: 'google.com',
  path: '/', // all paths
  expires: 0 // never expires
}).then(function() {
  // callbacks go here
});

Note that unlike native APIs, no further steps are required to ensure this cookie works with HTTPS hosts – this is enabled by default.

Fix double-offset status bar in Ionic and MFP for iOS 7+

Ionic has automatic functionality for offsetting content to allow for iOS 7+’s transparent status bar, and MFP also introduces logic for this behaviour.

The combination of these two corrections leads to an over-correction, with ion-nav-view content floating 22px below the status bar.

You can fix this by editing the iphone/css/main.css file and replacing the #wl_ios7bar and body.wl_ios7 rules with the following:

#wl_ios7bar{
    display: none;
}
body.wl_ios7{
     padding-top: initial;
}

NB. This does not show itself on projects that use Ionic’s ion-side-menus pattern.

Change iOS status bar text colour

This is a two-stage process in MobileFirst Platform (Worklight).

Turn off view controller-based status bar appearance

In Xcode, Head to your project’s “Info” tab, and open the “Custom iOS Target Properties” section:

Screen Shot 2015-02-24 at 10.10.13

If you already have a property named “View controller-based status bar appearance”, set its value to NO.

Otherwise, to add it, hover over an existing property. Two icons will appear: + and -. Click +, and type “View controller-based status bar appearance”. You’ll notice this is auto-completed for you. Set the new property’s value to NO.

Additionally, you can opt to initially hide the status bar while the splash screen is showing. To do this, add another new property “Status bar is initially hidden” with value YES.

Instruct Cordova to change the appearance

Insert the following into the wlEnvInit() function in your iphone/js/main.js file:

    if (window.StatusBar) {
        // Relies on UIViewControllerBasedStatusBarAppearance false
        window.StatusBar.styleLightContent();
        //window.StatusBar.styleDefault();
        //window.StatusBar.styleBlackTranslucent();
        //window.StatusBar.styleBlackOpaque();

        // Show bar if it was initially hidden
        window.StatusBar.show();
    }

The above instructs Cordova to style the status bar with light text, and then show it if it was hidden. This function is provided by Cordova’s StatusBar plugin, included in all hybrid applications by MobileFirst Platform.

You can read more about the StatusBar plugin, and the functions it provides to change status bar appearance, here.

Custom icons and splash screens in IBM MobileFirst Platform

I have to create custom application icons and splash screens for nearly every application I create with IBM Mobile First Platform.

Mostly, I have to work with iOS and Android applications, and I’ve now found a process and a set of tools that makes this a lot quicker.

NOTE: I’ll be concentrating on tools that work with Mac OSX exclusively, as I’m assuming you have access to this for creating your iOS hybrid applications.

Pre-requisites

I’m assuming you have a pre-existing MFP hybrid application project with an Android and iPhone (iOS) environment added to it. For the sake of argument, I’ll assume your project is called “MyProject” and the application is called “MyApp”. This results in a directory structure like MyProject/apps/MyApp.

The following commands will create an appropriate application:

mfp create MyProject
cd MyProject
mfp add hybrid MyApp
cd apps/MyApp
mfp add environment iphone
mfp add environment android

Create application icons

Firstly, create a 1024px x 1024px PNG icon file. You can use whichever editor you prefer for this. Generally, I use GIMP.

Don’t worry about rounded corners or anything – iOS will do this for you automatically, though Android will not. Transparency is preserved if you need it.

Once you have this file, you can feed it into the generation tools to make all the various sizes of icons you need.

Generating Android icons

Head over to makeappicon.com. Drop your 1024px x 1024px PNG file into the toaster. Once your files are “baked”, select the “Android” tab and get the website to email you your files.

Installing Android icons

The email you receive will have a ZIP file attached, with the following content:

Screen Shot 2015-02-19 at 13.32.52

Each of the android/drawable-* folders will contain an ic_launcher.png file. You need to copy these into your Android resource folder in your hybrid project.

cp -r icon/android/* MyProject/apps/MyApp/android/native/res

Make sure you adjust the command above to allow for your folders’ locations.

Now, adjust your android/native/AndroidManifest.xml file. You need to adjust the application element’s android:icon attribute to read @drawable/ic_launcher, like so:

<application android:label="@string/app_name" 
    android:icon="@drawable/ic_launcher">

This tells Android to use the ic_launcher.png files, not the pre-exisiting icon.png files. You can delete the icon.png files if you wish.

Generating iOS icons

You may have noticed that the archive you received from makeappicon.com included iOS icons, but unfortunately it’s an incomplete set. Thankfully, there’s an application that simplifies creation of the full set of iOS application icons, along with iOS splash screens.

Mark Bridges’s Asset Catalog Creator really helps out here. There are two versions; Asset Catalog Creator, and Asset Catalog Creator Free. Later on, you’ll need either the paid-for version (£1.49) or an in-app purchase from the free version (£0.79) to create iOS splash screens. I bought the full version.

Once you have the application installed, start it up and drag your 1024px x 1024px PNG icon file into the drop area, then generate the “iOS icon” asset catalog.

Installing iOS icons

Asset Catalog Creator has now generated an “asset catalog” – this is a really simple way of installing the icons into your iOS application. It also tells you how to install it, but in case you missed it, follow these instructions:

Open the iOS project in XCode. You can do this by opening MyProject/apps/MyApp/iphone/native/MyProjectMyAppIphone.xcodeproj with XCode.

Under the “General” tab in your project properties, find the “App Icons and Launch Images” section. Under “App Icons Source”, click “Use Asset Catalog”.

Screen Shot 2015-02-19 at 14.07.05

Choose to migrate existing app icons, and to migrate launch images. We’ll fix this up in a moment.

Drag the Media.xcassets folder generated by Asset Catalog Creator into your project root in XCode. Ensure you check “Copy items if needed” to install a copy of the files.

Screen Shot 2015-02-19 at 14.09.05
Screen Shot 2015-02-19 at 14.06.46

Click on the Media.xcassets folder. You’ll see several “sets” of resources: AppIcon (your new icons), AppIcon-1 (your old icons) and LaunchImage (your old splash screens). Make a note of the resource set you want to use as your application icons.

Now, go back to the “General” tab in your project properties, and select the correct resource set in “App Icons Source”.

Screen Shot 2015-02-19 at 14.18.39

Create splash screens

iOS is easiest and very similar to the iOS icons, so we’ll do that first.

Generating iOS splash screens

You’ll need a 2048px x 2048px version of your splash screen. Asset Catalog Creator can stretch, fit and crop this in various ways to generate all the versions you’ll need.

Using a method similar to that for iOS icons, use Asset Catalog Creator to create a set of iOS splash screens.

Installing iOS splash screens

Drag the generated LaunchImage.launchimage folder into the Media.xcassets folder in XCode:

Screen Shot 2015-02-19 at 14.24.54

Now, go back to the “General” tab in your project properties, and select the correct new resource set in “Launch Images Source”.

Screen Shot 2015-02-19 at 14.26.12

Generating Android splash screens

Android uses a special image format to create splash screens, known as a “9-patch image”. In the context of splash images, you’re only interested in marking up the “stretchable” areas of your image – you don’t have any content to “fill” the background with.

Take a look at Radley Marx’s guide and Google’s guide on 9-patch images.

There are many alternatives available for creating 9-patch images. I recommend the Android Asset Studio’s Simple Nine-patch Generator for basic splash screens. Alternatively, you could use the draw9patch tool included with the Android SDK.

Regardless, bear in mind that both of these tools are limited in capability when handling large images. I’d recommend a maximum size of 512px x 512px as a starting point.

Make sure you name your images splash.9.png.

Installing Android splash screens

Once you have generated your images using the tool of your choice, copy them into the appropriate drawable-* folders. If you have only one image, replace the drawable/splash.9.png image with it. Otherwise, delete any splash.9.png images you haven’t overwritten.

Conclusion

That’s it! Go ahead and compile your applications. Everything will look lovely.

Fixing “WLJQ is not defined” errors

This may also manifest as errors like:

  • WL.Client is not defined
  • Uncaught TypeError: Cannot read property 'init' of undefined

This is caused by MFP/Worklight failing to correctly munge the main HTML file for your app.

Because of this, two JS files don’t get loaded:

<script src="worklight/wljq.js"></script>
<script src="worklight/worklight.js"></script>

These files define WLJQ and WL.Client. Consequently, if they’re not loaded, your app code (see initOptions.js) won’t work.

Don’t hack those lines in manually – MFP expects to do this itself.

When using the CLI

  1. In a terminal enter:
    mfp stop
    rm -r $TMPDIR/wlBuildResources
    rm -r $TMPDIR/wlPreview
    mfp build
    mfp deploy
    

When using Eclipse

  1. Quit Eclipse (and thus the MFP preview server)
  2. In a terminal enter:
    rm -r $TMPDIR/wlBuildResources
    rm -r $TMPDIR/wlPreview
    
  3. Restart Eclipse and the preview server.
  4. Build and deploy.

The above instructions should work for Linux and OSX. On Windows, you may find the wlBuildResources and wlPreview directories in C:\temp, or the directory referred to by the TMP environment variable.

.gitignore for Worklight

I have recently started maintaining a .gitignore template file for IBM Worklight Foundation on github, in a similar spirit to the standard gitignore repository. Please feel free to take a look; just copy the Worklight.gitignore file into the root of your Worklight project, and rename it to .gitignore – then you’re ready to go.

It’s unofficial, and possibly not complete/accurate, so caveat emptor – any pull requests for fixes or enhancements will be gladly received.