25
1 IBM Worklight hands on lab: First steps in Worklight Table of contents TABLE OF CONTENTS .................................................................................................................................................................. 1 INTRODUCTION .......................................................................................................................................................................... 2 REQUIRED SOFTWARE ................................................................................................................................................................ 2 INSTALLING WORKLIGHT STUDIO ............................................................................................................................................... 3 CREATING A WORKLIGHT PROJECT ............................................................................................................................................. 6 FIRST STEPS IN WORKLIGHT ENVIRONMENT .............................................................................................................................. 9 FILE STRUCTURE .................................................................................................................................................................................. 9 DEVELOPMENT INTERFACE..................................................................................................................................................................... 9 TESTING YOUR APPLICATION.................................................................................................................................................... 11 DOJO MOBILE INTRODUCTION ................................................................................................................................................. 12 WHAT IS DOJO AND WHY USE IT IN YOUR PROJECT? ................................................................................................................................. 12 CREATING A NEW WORKLIGHT APPLICATION ........................................................................................................................... 13 APPLICATION DEPLOYMENT TO ANDROID/IOS......................................................................................................................... 21 CREATING A NEW ANDROID VIRTUAL DEVICE .......................................................................................................................................... 21 DEPLOYMENT FOR ANDROID IN WORKLIGHT ........................................................................................................................................... 22

IBM Worklight hands on lab: First steps in Worklight · PDF fileIBM Worklight hands on lab: First steps in Worklight ... simply right-click on NewsApp ... scroll to part ^NewsApp

Embed Size (px)

Citation preview

Page 1: IBM Worklight hands on lab: First steps in Worklight · PDF fileIBM Worklight hands on lab: First steps in Worklight ... simply right-click on NewsApp ... scroll to part ^NewsApp

1

IBM Worklight hands on lab: First steps in Worklight

Table of contents

TABLE OF CONTENTS .................................................................................................................................................................. 1

INTRODUCTION .......................................................................................................................................................................... 2

REQUIRED SOFTWARE ................................................................................................................................................................ 2

INSTALLING WORKLIGHT STUDIO ............................................................................................................................................... 3

CREATING A WORKLIGHT PROJECT ............................................................................................................................................. 6

FIRST STEPS IN WORKLIGHT ENVIRONMENT .............................................................................................................................. 9

FILE STRUCTURE .................................................................................................................................................................................. 9

DEVELOPMENT INTERFACE ..................................................................................................................................................................... 9

TESTING YOUR APPLICATION .................................................................................................................................................... 11

DOJO MOBILE INTRODUCTION ................................................................................................................................................. 12

WHAT IS DOJO AND WHY USE IT IN YOUR PROJECT? ................................................................................................................................. 12

CREATING A NEW WORKLIGHT APPLICATION ........................................................................................................................... 13

APPLICATION DEPLOYMENT TO ANDROID/IOS......................................................................................................................... 21

CREATING A NEW ANDROID VIRTUAL DEVICE .......................................................................................................................................... 21

DEPLOYMENT FOR ANDROID IN WORKLIGHT ........................................................................................................................................... 22

Page 2: IBM Worklight hands on lab: First steps in Worklight · PDF fileIBM Worklight hands on lab: First steps in Worklight ... simply right-click on NewsApp ... scroll to part ^NewsApp

2

Introduction Welcome to the first part of Worklight tutorial. This lab will guide you through installation of environment needed to

develop applications for Worklight platform, creating your first application and enhancing its possibilities with DoJo

toolkit.

The application is called NewsApp and is designed to show easily-readable form of designated RSS feed.

Programming of this app is structured into several steps, which allows you to fully comprehend development of

hybrid applications using the Worklight platform and web techniques, such as HTML5, CSS and JavaScript. Interface

of the app is created using prepared components of DoJoX Mobile toolkit. DoJo toolkit as such is bundled with IBM

Worklight solution.

After completion of this lab you should have gained understanding of:

Installation of IBM Worklight Studio

How to create a Worklight project and Worklight application

Development techniques and procedures in WL Studio

File structure of WL Project

Basic usage and principles of DoJo Mobile

For full understanding of all steps you should possess basic knowledge of HTML, CSS and JavaScript. Familiarity with

the Eclipse platform is a plus, but not required.

Required software

Eclipse IDE 3.6.2+

(Any version with exception of Eclipse Classic, which doesn’t contain Eclipse Marketplace Client)

http://www.eclipse.org/downloads/

Java SDK http://www.oracle.com/technetwork/java/javase/downloads/index.html

Firefox 3.6+

Internet Explorer 8+

Safari 5.0+

(These internet browsers are capable of Eclipse in-app preview of the application build by DoJo mobile, at least one of them is required!)

Page 3: IBM Worklight hands on lab: First steps in Worklight · PDF fileIBM Worklight hands on lab: First steps in Worklight ... simply right-click on NewsApp ... scroll to part ^NewsApp

3

Installing Worklight Studio 1. Open the Eclipse IDE

2. Select Help > Eclipse Marketplace… from main menu.

3. In the newly opened window type “Worklight” into the Find input on Search tab and click Go.

4. In a few moments Eclipse should return only one result – “IBM Worklight Developer Edition”. Verify, that

it’s genuine IBM product and click Install.

Page 4: IBM Worklight hands on lab: First steps in Worklight · PDF fileIBM Worklight hands on lab: First steps in Worklight ... simply right-click on NewsApp ... scroll to part ^NewsApp

4

5. Eclipse will download required information and offer you all possible features of Eclipse solution. Make sure

that all checkboxes are checked and click Next button.

6. In the following dialog, review licenses, check “I accept the terms of the license agreements” and click

Finish.

Page 5: IBM Worklight hands on lab: First steps in Worklight · PDF fileIBM Worklight hands on lab: First steps in Worklight ... simply right-click on NewsApp ... scroll to part ^NewsApp

5

7. Eclipse will now download all required files and install them. Depending on speed of your internet

connection, this may take up to 15 minutes.

8. After installing all components, you will be asked to restart your IDE. Make sure you have all your work saved

and click Yes.

9. Congratulations, you’ve completed installation of IBM Worklight platform! Now you can proceed to creating

your first application.

Page 6: IBM Worklight hands on lab: First steps in Worklight · PDF fileIBM Worklight hands on lab: First steps in Worklight ... simply right-click on NewsApp ... scroll to part ^NewsApp

6

Creating a Worklight project 1. After installing the IBM Worklight solution from Eclipse Marketplace, notice the blue Worklight icon in main

bar. Click this icon and select Worklight Project.

2. In the New Worklight Project window type name of your new project – FirstWorklightProject, select Hybrid

Application project template and click Next.

3. On the next window, type name of the new application – NewsApp, check the “Add Dojo Toolkit” option

and click Finish.

If you want to use jQuery Mobile, or Sensa Touch toolkits, you can select and locate them in this step –

Worklight will automatically add them to current project.

Page 7: IBM Worklight hands on lab: First steps in Worklight · PDF fileIBM Worklight hands on lab: First steps in Worklight ... simply right-click on NewsApp ... scroll to part ^NewsApp

7

.

4. Eclipse will automatically offer you to open Design perspective, click Yes.

5. You’ve successfully created a new project with sample application! Eclipse will now open application-

descriptor.xml, which allows you to set basic settings of your application.

Basic behavior of your application is set by this file. Address of the Worklight server (set to localhost:8080 by

default), displayed name of the application in Worklight server, etc. Authentication settings can be found

under the Usage item in the Overview tree.

Application Environments and Skins can be managed from Overview tree on the left side of Design view of

application-descriptor.xml file. All settings can be changed directly in source code of this file. Just click on

Source tab at the bottom of the editor window.

Page 8: IBM Worklight hands on lab: First steps in Worklight · PDF fileIBM Worklight hands on lab: First steps in Worklight ... simply right-click on NewsApp ... scroll to part ^NewsApp

8

Page 9: IBM Worklight hands on lab: First steps in Worklight · PDF fileIBM Worklight hands on lab: First steps in Worklight ... simply right-click on NewsApp ... scroll to part ^NewsApp

9

First steps in Worklight environment

File structure

A Worklight Project consists of the following folders:

/adapters – Contains the project’s adapters. Adapters connect your

application to another data-source, such as webserver, database, or Cast

Iron service.

/apps – Contains the project’s applications.

/common – Code and resources shared for all environments. If any other

environment contains resources/code with same name, resources from

common folder are suspended in favor of platform-specific resources.

/legal – Folder for legal documents, such as license agreement.

application-descriptor.xml – File containing settings for whole application.

/dojo – Folder with DoJo toolkit, added by Worklight – if selected in

process of creating new application.

/server – Server-side configuration and support files.

Development interface

Open /apps/NewsApp/common/NewsApp.html by double-clicking on its name. On the upper half of the screen you

can see preview of application, and on the lower half is its source code. There are several important elements in this

view:

1) Open/Close Media View panel and Properties. This panel will show you all views used in your application.

Functionality of view will be explained further in this lab. For current needs you have to know, that view is

element of DoJoX Mobile toolkit. Basically one view means one page in your application.

Properties Explorer is used to easily set all attributes of HTML/CSS/JS elements in Design View of any html

file.

2) Change browser rendering the preview. FF stands for Firefox, IE for Internet Explorer and S for Safari. After

every change in source code is preview updated, but you can update it manually by clicking on icon of two

arrows next to Preview browser selection.

3) Select target device and skin. For preview how your application will look like and behave with different

screen resolutions and aspect ratio.

4) List of DoJo Mobile Widgets. List of all supported prepared components, can be drag-n-dropped directly into

preview or source code of application.

5) Tabbar for perspective switching. Developing in split view may be difficult, so here you can change your

perspective to design-only or source-only view. It’s recommended to develop in source code view, because it

allows you to have absolute control over the code.

Page 10: IBM Worklight hands on lab: First steps in Worklight · PDF fileIBM Worklight hands on lab: First steps in Worklight ... simply right-click on NewsApp ... scroll to part ^NewsApp

10

Page 11: IBM Worklight hands on lab: First steps in Worklight · PDF fileIBM Worklight hands on lab: First steps in Worklight ... simply right-click on NewsApp ... scroll to part ^NewsApp

11

Testing your application 1. To deploy your application to Worklight Server, simply right-click on NewsApp folder and select Run As >

Build All and Deploy. Eclipse will automatically launch an instance of Worklight Server and deploy your

application. You can monitor progress in a console (Window > Show View > Console), which will pop-up

instantly after you start building an app. After several moments you will see a confirmation of successful

deployment:

Application 'NewsApp' deployed successfully with all environments

2. Unless you changed settings of Worklight Server, or have any other application occupying 8080 port, default

address of Worklight Console is http://localhost:8080/console/

3. Because we haven’t used any Adapter or Environment, you won’t see much in a Worklight Console. Most

important link for now is Preview as Common Resources, which allows you to see preview of your

application in browser of your choice. For full experience is recommended to resize browser window to

smaller dimensions for credible mobile device simulation.

Page 12: IBM Worklight hands on lab: First steps in Worklight · PDF fileIBM Worklight hands on lab: First steps in Worklight ... simply right-click on NewsApp ... scroll to part ^NewsApp

12

DoJo Mobile introduction

What is DoJo and why use it in your project?

Dojo Toolkit (http://dojotoolkit.org/) is an open source JavaScript toolkit. It is supposed to ease and speed up

development of cross-platform web sites and applications.

Dojo Mobile is a part of DoJo toolkit designed for mobile application development. It enables rapid development of

mobile web HTML5 applications with a native look and feel on modern webkit-enabled mobile devices such as

iPhone, iPod Touch, iPad, Android and RIM smartphones and tablets.

Of course, DoJo Mobile is one of several solutions how to quickly develop native look applications. Other open-source

alternatives are for example jQuery Mobile (http://jquerymobile.com/) or Sensa Touch

(http://www.sencha.com/products/touch/). Worklight is very open platform and isn’t forcing you to use any of

previously mentioned toolkits. You may use another JavaScript toolkit, your own framework or even just plain HTML.

If selected on creating of a new Project, Worklight will add DoJo toolkit into your app. Each component, which do

you want to use in your project must be required in the application header tag. When do you use WYSIWYG editor

and drag-n-drop functions, Worklight will declare all required components for you. Otherwise you have to keep in

mind that every DoJo component must be required in html header, otherwise won’t function properly.

DoJo Mobile comes with a number of prepared widgets. Most important widgets are:

View – A virtual “page” in mobile application. Each view has unique id, which allows you to navigate

between them. You can have multiple views in one page (even nested into each other), but only one view

can be visible at a time. All views have selected attribute. The view with selected=true will be displayed at

start of the app.

ScrollableView – Subclass of View having a touch scrolling capability. Header and footer can be fixed, thus

only the page content is scrolled.

SwapView – Subclass of View allowing user to swipe the screen to left/right and move between the

SwapViews.

Heading – Heading of the application, can contain a navigational buttons (ToolBarButton).

TabBar – Container widget usually with more TabBarButtons, which navigate user through several Views.

Can be switched to segmented control mode, which has same functionality but different look.

Button – Simple button, skinned to fit application look & feel.

RoundRect – Simple round rectangle container for another widget or HTML content.

RoundRectList – Round rectangle list nesting ListItems.

ListItem – Single item of a list, can contain icon and link to another View.

Now when you are familiar with basic components, we can proceed to enhancing our first Worklight application.

Page 13: IBM Worklight hands on lab: First steps in Worklight · PDF fileIBM Worklight hands on lab: First steps in Worklight ... simply right-click on NewsApp ... scroll to part ^NewsApp

13

Creating a new Worklight application 1. First of all, we need to delete sample code generated by Worklight – in Source or Split view of

NewsApp.html scroll to part “NewsApp <!-- application UI goes here -->” and delete it.

2. If you haven’t opened it yet, open Mobile View by clicking on “Show / Hide Mobile Views” icon

3. Click on New icon with add symbol.

4. In newly opened window, select ScrollableView and click Next

Page 14: IBM Worklight hands on lab: First steps in Worklight · PDF fileIBM Worklight hands on lab: First steps in Worklight ... simply right-click on NewsApp ... scroll to part ^NewsApp

14

5. Name new View “scrollView”, set it as default and include heading with “News feed” label. Click Finish. As

you may see in the source view, Worklight automatically adds all necessary DoJo requirements.

6. Repeat step 4 and 5 to add another ScrollableView called “settView”, include heading with “Settings” label.

Erase any generated Back button target and do not set this view as default! Use same procedure to create

“aboutView” with “About” label.

Only one view can be set as default – default View is displayed at the start of application.

Page 15: IBM Worklight hands on lab: First steps in Worklight · PDF fileIBM Worklight hands on lab: First steps in Worklight ... simply right-click on NewsApp ... scroll to part ^NewsApp

15

7. Your Mobile View Explorer should now look like this. If you want to change currently previewed View, just

click eye icon next to View name. For now select aboutView as current previewed View.

8. Now it’s time to add some element to navigate between recently added Views. One of the possibilities is

TabBar. Switch your view of NewsApp.html to Design perspective using tabs on the bottom of editor

window. Verify that you are previewing for Apple iPhone 4 and 4s (1). Then scroll down in the preview

window to the bottom of the page (2). And finally, from the Pallete on right side of the screen pick TabBar

from DoJo Mobile Widget section and drag it to the right side of preview window as shown on picture. After

Worklight offers you to “Insert into <body> ‘content’ after ScrollableView ‘aboutView’”, release mouse

button and that’s it!

Page 16: IBM Worklight hands on lab: First steps in Worklight · PDF fileIBM Worklight hands on lab: First steps in Worklight ... simply right-click on NewsApp ... scroll to part ^NewsApp

16

9. Add three new buttons by dragging TabBarButton widget into recently added TabBar as shown on following

picture:

10. Add three icons for newly created buttons. These buttons will allow user to navigate through app Views –

News Feed, Settings and About. Size is optional, but for best results use dimension of 32 x 32 pixels. Copy

Page 17: IBM Worklight hands on lab: First steps in Worklight · PDF fileIBM Worklight hands on lab: First steps in Worklight ... simply right-click on NewsApp ... scroll to part ^NewsApp

17

files from /icons directory (same root directory, where you’ve found this file) into /common/images folder

and confirm copying by selecting “Copy files” and clicking OK.

11. Configure each button by clicking on its label in design view and modify it in Properties Explorer. For each

button set Label, Icon (click on folder icon next to Icon input to browse for available images), Transition

destination and Transition effect.

If you don’t understand what are you supposed to do, proceed to the next step, where you can see the result!

Page 18: IBM Worklight hands on lab: First steps in Worklight · PDF fileIBM Worklight hands on lab: First steps in Worklight ... simply right-click on NewsApp ... scroll to part ^NewsApp

18

12. Open your code in Source view. Locate following part of the code and add style="margin-top: -50px;" as

shown in following code. Check if everything in the code is same as here. If not, copy missing parts into your

project.

<ul data-dojo-type="dojox.mobile.TabBar" style="margin-top: -50px;" data-dojo-props="fixed:'bottom'"> <li data-dojo-type="dojox.mobile.TabBarButton" data-dojo-props="moveTo:'scrollView',transition:'slide', icon:'images/rss.png'" selected="true">News Feed</li> <li data-dojo-type="dojox.mobile.TabBarButton" data-dojo-props="moveTo:'settView',transition:'slide', icon:'images/settings.png'">Settings</li> <li data-dojo-type="dojox.mobile.TabBarButton" data-dojo-props="moveTo:'aboutView',transition:'slide', icon:'images/info.png'">About</li>

</ul>

13. Now it’s time to fill your application with some content. For now even a hard-coded content will be

sufficient. Dynamicaly inserted content will follow in further parts of this lab.

We will now demonstrate howto use prepared DoJo Mobile Widgets even in Source view. Open Source view

of NewsApp.html, locate div with id=”scrollView” and drag RoundRectList into this element, as show on

picture (1):

As you can see, ListItem is automaticaly generated into new RoundRectList. Click on it (2) and in Properties

Explorer set Label to “Work in progress…”.

14. Repeat step 13 for div with id=”settView”.

15. Locate div with id=”aboutView” and drag RoundRect Widget into the content of aboutView View.

16. You don’t have to use only DoJo Mobile Widgets, use of ordinary HTML Tags is also possible. Drag Heading 1,

Heading 2, Image and two Paragraphs from HTML Tags Palette into newly added RoundRect of div with

id=”aboutView”.

Page 19: IBM Worklight hands on lab: First steps in Worklight · PDF fileIBM Worklight hands on lab: First steps in Worklight ... simply right-click on NewsApp ... scroll to part ^NewsApp

19

17. Complete code with everything shown in picture above. Text in paragraphs isn’t important and can be

changed to any random text. Don’t forget to add class atributes to all elements and wrap img into separate

div.

Now open /common/css/NewsApp.css and add following items:

.title { font-size: 120%; font-weight: bold; } .subtitle { color: grey; } .aboutImg { text-align: center; margin: 10px 0 10px 0; } .ptext { text-align: justify; font-size: 90%; margin-bottom: 5px; }

18. Set id of RoundRectList in first ScrollableView (with heading News feed). New id is “newsList”. Unless you

set an id, you won’t be able to locate this component in your JavaScript code. We will use this ID later in this

lab.

Congratulations! You’ve created your first HTML5 application in Worklight with help of DoJo Mobile toolkit. Now it’s

time to deploy and test application in real world – outside the Eclipse preview mode.

Page 20: IBM Worklight hands on lab: First steps in Worklight · PDF fileIBM Worklight hands on lab: First steps in Worklight ... simply right-click on NewsApp ... scroll to part ^NewsApp

20

For example in Chrome internet browser our current application looks like this:

Till closing of Eclipse the Worklight Server remains launched and application web address is available for all

applications. This is very useful for example when you want to use advanced development and testing tools,

such as FireBug extension.

SELF-EXAMINATION: Use newly gained experience to enhance “Settings” page of your application. Feel free

to use any DoJo Mobile Widgets. DoJo Mobile Showcase may become useful – you can find it on

http://demos.dojotoolkit.org/demos/mobileGallery/demo-iphone.html. Another resource is official

documentation place dat http://dojotoolkit.org/reference-guide/1.7/dojox/mobile.html#dojox-mobile.

Keep in mind, that the content is not important at the moment. Feel free to use any components you may

find useful.

Page 21: IBM Worklight hands on lab: First steps in Worklight · PDF fileIBM Worklight hands on lab: First steps in Worklight ... simply right-click on NewsApp ... scroll to part ^NewsApp

21

Application deployment to Android/iOS ANDROID NOTE: Already installed Android SDK and Eclipse ADT are required. SDK is available for download at

http://developer.android.com/sdk/. Installation of Eclipse Android Development Tools is described on

http://developer.android.com/sdk/installing/installing-adt.html. Open Android SDK manager and download all

necessary parts for Android 4.1 – API Level 16 as well.

IOS NOTE: Already installed Xcode is required. You can find it in your Mac App Store or at

https://developer.apple.com/xcode/.

Creating a new Android Virtual Device

Before you may test any application on Android platform, you have to add Android Virtual Device (AVD). AVD is a

completely virtual Android device with most of its real-world functionality. Sadly virtual devices are slower than real

ones, so make sure to test your applications on real devices as well.

1. Open Android Virtual Device Manager by clicking on its icon located in main Eclipse toolbar.

2. In newly opened window click New.

3. Now set details of newly created device. Change name to avd41, select Android 4.1 – API Level 16 as Target

platform. For better performance, increase Device ram size to at least 1024 MB. Finally, click on Create AVD

button to finish creation process.

Page 22: IBM Worklight hands on lab: First steps in Worklight · PDF fileIBM Worklight hands on lab: First steps in Worklight ... simply right-click on NewsApp ... scroll to part ^NewsApp

22

Deployment for Android in Worklight

Deployment for Android platform is very easy. To deploy on new platform, all you need to do is add a new Worklight

Environment to your project. Just locate blue Worklight icon on main Eclipse toolbar and select Worklight

Environment.

In newly opened windows select project, which do you want to use and also select application and desired platform.

In our case Android phones and tablets.

Page 23: IBM Worklight hands on lab: First steps in Worklight · PDF fileIBM Worklight hands on lab: First steps in Worklight ... simply right-click on NewsApp ... scroll to part ^NewsApp

23

IMPORTANT: Notice the newly created folder “android” in /apps/NewsApp. This folder contains same directory

structure as common directory (css, images, js). This has a very good reason – if you, for example, place icon.png into

common/images folder and different icon.png into android/images folder – during build for android platform will be

used icon.png from android folder. Same procedure applies for all files and even for a single JavaScript functions. Any

function then may have different implementation on each Environment without any difficulties. Imagine function

getUserResponse() with various internal functionality on each platform.

Worklight will also automatically build a new Android project called FirstWorklightProjectNewsAppAndroid. By

running this project as Android application (Right click > Run As > Android Application) you’ll launch Android

Emulator with your app deployed. Full emulator functionality is available. If you have any Android device connected

to your computer (with activated USB Development mode), you’ll be offered to lunch it or real device.

Page 24: IBM Worklight hands on lab: First steps in Worklight · PDF fileIBM Worklight hands on lab: First steps in Worklight ... simply right-click on NewsApp ... scroll to part ^NewsApp

24

WARNING: Due to unfixed error in Android 2.3.3. Emulator (http://code.google.com/p/android/issues/detail?id=12987)

may your app crash while tested in emulator. Solution is easy – try your application in other versions, such as

Android 2.2. This doesn’t affect real devices!

Deployment on Apple iOS is very similar – after adding an Apple Environment will Worklight perform a build for

Apple iOS. By running app as Xcode project (Run As > Xcode project) will launch Xcode IDE and iOS emulator.

Page 25: IBM Worklight hands on lab: First steps in Worklight · PDF fileIBM Worklight hands on lab: First steps in Worklight ... simply right-click on NewsApp ... scroll to part ^NewsApp

25

After adding new Worklight Environment you may notice more options in Worklight Console. Very useful option is

Java-based web emulator of target device. You’ll find it under the eye icon next to app name.