Using Worklight Studio, developers can simply add environments to their Worklight application and start writing code that is specific to multiple mobile or web environments. If you need to maintain a version of your IBM Worklight application for any specific mobile platform, then you should add the environment that originated from a particular platform to your application. For instance, if you want to create an Android version of your Worklight app, you must add an Android environment. When you start adding an environment in your application, it actually creates a new folder, called the common folder, for that specified environment. It contains all the resources for that new environment.
While creating a project in Worklight, it creates a common folder within the app to use web technologies such as HTML5 and JS to implement UI and logic with frameworks such as jQuery and Dojo. This common folder stores its files in the following structure:
The Worklight Common Folder structure
If we move on this folder hierarchy, the images folder holds images; these images override existing images with the same names in the common environment. The css folder holds styling files that override or extend the CSS and stylesheet files in the common environment, while the js folder holds JavaScript files that override the common JavaScript objects within the application. The class that is defined in the desired environment folder overrides the common app class. Finally, the new HTML file extends the prebuilt HTML file in common Worklight environment that has a similar name.
The common folder in the Worklight application is responsible for holding the code you write to design or develop pages. Other resources are transferred from this folder to several environments.
Let's start with adding the Android environment to our Dojo sample app, which we created in the previous chapter. Please perform the following steps:
- Open your application in Worklight Studio or Eclipse. To learn how to create a Worklight project, please have a look at the previous chapter. The following screenshot shows the structure of a Worklight application in Project Explorer:
The Worklight project structure diagram
- To add the Android environment into your Worklight application, right-click on the project and follow the menu as shown in following screenshot, and navigate to New | Worklight Environment.
- It will open the Worklight Environment window, where you need to fill up the required values for adding an environment in your project. Include the Project name combobox for the selection of a Worklight project and the Application/Component combobox to select a Worklight application. Finally, select the Android environment checkbox between other environment checkboxes as shown in the following screenshot:
Adding a mobile/desktop Worklight environment
- Click on the Finish button.
After completion of all the preceding steps, you can see the android folder structure as shown in the following screenshot:
The Android environment
Now, we can move on with a brief description regarding specific environment resources.
The Worklight platform allows developers to write applications by means of web or native technologies. Both technologies can also be used in a single app. Both web and native client-side app resources must be placed under the common folder with a predefined structure. Depending on the environment selection, IBM Worklight Studio uses the application folder to generate and build these resources into the app folder. However, to maintain production quality, you should provide all defined resources that are mandatory for those environments in which the application is executed.
The descriptor file contains metadata that is used to declare and define various facets of the native API for the Android application.
This application-descriptor is written and can be modified in XML and a mandatory file that allows you to store metadata in the root directory of the application. This application descriptor file is automatically generated by Worklight Studio when you initiate or create a Worklight application. In addition, this file can be improvised to add some custom properties.
This metadata file handles property identifications, which will be used to declare various attributes of the application. Worklight provides this file, named application-descriptor.xml, located in the application's root directory.
The following code example shows the format of the the application-descriptor.xml file for native API applications for Android:
<?xml version="1.0" encoding="UTF-8"?>
<nativeAndroidApp
id="android"
platformVersion="5.0.5"
securityTest="security test name"
version="1.0"
xmlns="http://www.worklight.com/native-android-descriptor">
<displayName>HelloWorld</displayName>
<description>HelloWorld</description>
<publicSigningKey>application public signing key</publicSigningKey>
</nativeAndroidApp>Let's understand line by line what it means to the application. To start with, the <nativeAndroidApp> tag is actually used to define the Android environment or added automatically when the developer adds the Android environment to the application. This is the key element as you can see it contains multiple attributes to configure the Android environment within the Worklight application. It has three mandatory attributes, while one is optional as follows:
id: This attribute defines the unique identification of the application. The ID should be unique to the name of the application folder. It must be a string that holds an alphanumeric character that must start with a letter. It may have an underscore '_' character.platformVersion: This contains the platform version of IBM Worklight that is used to build or develop the application.version: This element is used to assign the version of the application. This value of theversionattribute is a string that contains the major and minor version numbers of the application. It is highlighted and visible on the Marketplace or App Store, wherever the application is deployed for users to download.securityTest: This attribute is optional but it is subjected to specify a security configuration. In case you give the client access to a protected resource, this security implementation checks the client authentication. In case of failure, Worklight initiates the process to authenticate based on the credentials passed on.
At the time of creating a Worklight application, one HTML file is constructed by IBM Studio. We name the HTML file with the name of your app and use it to control and design the UI of the application. This file is responsible for loading all the resources that contain JavaScript and CSS. We need these to define the common elements of the application, in which a script file is used to obtain the document events.
This main HTML file is located in the app/common directory and must contain a body tag, and to set as content you must have the Id attribute defined in the body tag. If the value is changed, the environment of the application is not initialized correctly.
JavaScript files are used to implement business logic and query integration between the backend and predefined structures such as challenge handlers and message dictionaries. These structures automatically translate the defined string according to the declared values in a designated file. All the scripts files are placed under the app/common/js folder. CSS files are used to style application views and are placed under the common/css folder.
The application icon is used to specify the graphical identification of the created app. The Worklight application comes with the default thumbnail image on creating the app. Replacing the icon image would override the default image. This image must be square and preferably of pixel 128 x 128 in size and placed under the common/images folder of the app.
IBM Worklight creates the default splash image for each application environment when adding the environment to the app. The splash screen loads with the image while the application is being initialized. As it applies only to mobile environments, the developer can change the default image by overriding it; the image dimension must be the same as that of the app. This splash image can be found under the [Environment]/native/www folder.
When adding an environment in the IBM Worklight application, Studio will create the required native API and the client property file for the corresponding environment in the Worklight project. The name and the content format are dependent on the selected environment.
Please follow this table for details in sequence:
|
Environment |
Worklight native and client properties |
|---|---|
|
iOS |
The The |
|
Android |
The The |
|
Java ME |
The The |
These are brief descriptions to determine the property files with respect to the environment.
The following screenshot shows you the Android resource hierarchy generated by deploying the app to the Android environment.
You must define the properties of this client property file before using it in your native app for Android.
The following table lists the properties of the wlclient.properties file, their descriptions, and possible examples for their values: