Magic RIA Client for BlackBerryftp.magicsoftware.com/ver/docs/Downloads/uniPaaS...Magic Software...
Transcript of Magic RIA Client for BlackBerryftp.magicsoftware.com/ver/docs/Downloads/uniPaaS...Magic Software...
Magic Software Enterprises Ltd., 5 Haplada Street, Or-Yehuda 60218, Israel
Tel: +972 (0)3 538 9292 | Fax: +972 (0)3 538 9333, +972 (0)3 538 9393 | [email protected] | www.magicsoftware.com
Magic RIA Client for BlackBerry
For uniPaaS Version 2.0
Installation Guide
Magic Software Enterprises Ltd., 5 Haplada Street, Or-Yehuda 60218, Israel
Tel: +972 (0)3 538 9292 | Fax: +972 (0)3 538 9333, +972 (0)3 538 9393 | [email protected] | www.magicsoftware.com
2
Contents Preface ................................................................................................................................................................. 3
Getting Started .................................................................................................................................................... 3
Prerequisites .................................................................................................................................................... 3
Setting-up the “build” environment ................................................................................................................ 3
Setting-up the uniPaaS environment .............................................................................................................. 4
Running the “build” tool .................................................................................................................................. 4
Usage ........................................................................................................................................................... 4
build_client.xml ........................................................................................................................................... 5
execution.properties ................................................................................................................................... 6
Deploying the Magic RIA client for BlackBerry .................................................................................................... 6
Installing and running the Travel Demo application ........................................................................................... 7
Travel Demo application walkthrough ............................................................................................................ 9
Magic Software Enterprises Ltd., 5 Haplada Street, Or-Yehuda 60218, Israel
Tel: +972 (0)3 538 9292 | Fax: +972 (0)3 538 9333, +972 (0)3 538 9393 | [email protected] | www.magicsoftware.com
3
Preface The Magic RIA client for BlackBerry is a native BlackBerry OS application implementing the Magic RIA client
protocol. Using the Magic RIA client for BlackBerry, developers can deploy enterprise connected, highly
interactive RIA applications to BlackBerry OS devices.
Getting Started The BlackBerry platform provides a managed, controlled process for installing native applications on
BlackBerry devices. Each Magic application that you want to deploy on the BlackBerry platform must be
packaged as a separate, self-contained BlackBerry application with its unique name, icon and application
properties. The process of building a BlackBerry application involves editing configuration files and running a
“build” tool that creates a new, unique BlackBerry application that embeds the Magic RIA client engine. This
application can then be deployed on BlackBerry devices using the supported distribution mechanisms.
Prerequisites To successfully build a Magic RIA BlackBerry application, the following prerequisites are required:
uniPaaS Studio 2.0 (Enterprise or Jet Edition) – For developing and testing the application.
The BlackBerry JDE version 5.0.0 – For creating the final packaged BlackBerry application.
The Apache ANT build tool version 1.8.2 or above – For running the “build” script.
Code-signing keys – For creating a signed application that can run on BlackBerry devices. You can
read about code-signing keys here.
A BlackBerry device simulator (optional) – For testing the application on the desktop.
Setting-up the “build” environment 1. Register as a developer on the BlackBerry developer site. This will enable you to download the
necessary tools. Registration can be done here.
2. Apply to receive code-signing keys from RIM here. Once approved, you will receive an email with the
code-signing keys. Follow the installation instructions in the email.
3. Extract the build_magic folder from the Magic RIA client for BlackBerry zip file to a folder that does
not have spaces in its name (i.e. to the root of the C: drive).
4. Download the BlackBerry JDE (Java Development Environment) version 5.0.0 from here, and install it
using its setup program.
5. The build_magic folder contains two configuration files: build_magic.xml and execution.properties.
These files should be edited to reflect the current configuration before running the build tool.
After installing the BlackBerry JDE, edit the build_magic.xml configuration file and modify the
jde.home and jde.version properties to reflect the installed location and version of the JDE.
Magic Software Enterprises Ltd., 5 Haplada Street, Or-Yehuda 60218, Israel
Tel: +972 (0)3 538 9292 | Fax: +972 (0)3 538 9333, +972 (0)3 538 9393 | [email protected] | www.magicsoftware.com
4
6. Download Apache ANT version 1.8.2 or above from here, and extract it into a new folder that does
not have spaces in its name. Follow the configuration instructions on this page to properly install and
configure this tool. Note that the configuration requires making changes in environment variables.
7. For testing purposes, a device simulator is recommended. Download and install a BlackBerry device
simulator from here. Choose a device with a minimum OS version of 5.0.0.
Setting-up the uniPaaS environment 1. Download and install the uniPaaS 2.0 Studio (Enterprise or Jet Edition).
2. Add the following lines at the end of the Magic RIA server magic.ini file:
[MAGIC_SPECIALS]
SpecialClientSecureMessages = N
If the Magic server is already running, restart it.
3. Edit the execution.properties file and modify the protocol, server and requester properties to
reflect the currently installed uniPaaS RIA server configuration.
4. In the execution.properties file, change the appname property to the name of your application.
5. In the execution.properties file, change the prgname property to the public name of the program
you want to run on client startup. This program must be defined in the application as External.
Running the “build” tool The build tool is a command file that handles the compilation and packaging of your application client. The
build tool has the following configuration files:
1. build_client.xml – This is the build configuration file. In this file you define the native BlackBerry
application properties such as application title, description and version.
2. execution.properties – This file is packaged together with the application file and is used by the
Magic RIA client to connect to the Magic RIA server. This file contains the server connection and the
Magic application details.
3. icon.png – This file will be is used as the application icon. It is recommended to use a 48x48 pixels
PNG file. Other file sizes are also acceptable, but will be resized to fit the device’s icon size.
Usage
From the build tool folder, run build.cmd. The build tool writes a log file of its operation. The log file is
named build.log and is created in the same folder as the build.cmd command file.
Note: Every build will overwrite the “output” folder. If you want to save previous build outputs, you need to
copy them elsewhere.
Magic Software Enterprises Ltd., 5 Haplada Street, Or-Yehuda 60218, Israel
Tel: +972 (0)3 538 9292 | Fax: +972 (0)3 538 9333, +972 (0)3 538 9393 | [email protected] | www.magicsoftware.com
5
build_client.xml
This configuration file contains the following parameters, editable using a text editor:
build.password – This password is required by the BlackBerry application signing utility.
jde.version – The JDE version used during the build. The default is 5.0.0.
jde.home – The home directory of the JDE installation.
output.dir – The folder that will contain the built installers. It can be an absolute or relative path.
build.dir – A temporary folder location used during the build process. This folder is removed after a
successful build. It can be an absolute or relative path.
source.jar.name – The name of the source Magic RIA JAR file. This file contains the core Magic RIA
client module.
cod.name – The target module name that will be created during build. Module names must not
contain spaces.
OTA.dir – The target folder for the web installer files (Over-the-Air). A relative path is created in the
output folder.
Desktop.dir – The target folder for the BES or BlackBerry Desktop installer files. A relative path is
created in the output folder.
client.title – The application title as visible to the user.
client.version – The application version.
client.description – A longer application description.
client.vendor – The vendor details.
client.copyright – The copyright message.
Example build_client.xml parameters:
<!--### JDE and signing properties ##########################################################--> <property name="build.password" value="******" /> <property name="jde.version" value="5.0.0" /> <property name="jde.home" location="C:\Program Files\Research In Motion\BlackBerry JDE 5.0.0" /> <!--### Build source and target properties ##################################################--> <property name="output.dir" location="output\" /> <property name="build.dir" location="output\build\" /> <property name="source.jar.name" value="Magic_RIA_20" /> <property name="cod.name" value="Magic_Travel_Demo" /> <property name="OTA.dir" value="OTA\" /> <property name="Desktop.dir" value="Desktop\" /> <!--### Application properties #############################################################--> <property name="client.title" value="Magic Travel Demo" /> <property name="client.version" value="1.0.0" /> <property name="client.description" value="The Magic Travel Demo" /> <property name="client.vendor.name" value="Magic Software Enterprise Ltd." /> <property name="client.copyright" value="Copyright (c) 2011 Magic Software Enterprises Ltd." />
Magic Software Enterprises Ltd., 5 Haplada Street, Or-Yehuda 60218, Israel
Tel: +972 (0)3 538 9292 | Fax: +972 (0)3 538 9333, +972 (0)3 538 9393 | [email protected] | www.magicsoftware.com
6
execution.properties
This configuration file contains the following parameters, which are editable using a text editor:
protocol – The name of the communication protocol used by the client. Can be HTTP or HTTPS.
server – The host name or IP address of the website hosting the Magic requester.
requester – The alias/virtual folder and module name of the Magic requester.
appname – The application name, as published to the Magic broker by the Magic RIA server.
prgname – The public program name to call on startup. This program is typically an application menu
or welcome screen.
Example execution.properties parameters:
<properties> <property key="protocol" val="http"/> <property key="server" val="127.0.0.1"/> <property key="requester" val="uniJetScripts/mgrqispi.dll"/> <property key="appname" val="unipax"/> <property key="prgname" val="mobile"/> </properties>
Deploying the Magic RIA client for BlackBerry The build process creates a native BlackBerry application that can be deployed like any other native
application. The BlackBerry platform supports several deployment methods for applications. A detailed
description of the different methods can be found in the following document. This document also contains
configuration instructions for the different deployment methods.
The build process creates two outputs that can be used for all supported distribution methods, in the
locations configured in the build_client.xml configuration files: OverTheAir and Desktop.
You can follow the instructions for both Over-the-Air (OTA) and Desktop installations in the referenced
document to install the client. Note that when using OTA deployment, it is necessary to change
configuration settings (MIME types) in the web server that is hosting the published application files.
Note: After deploying the application client, there is no need to redeploy it after every application change.
The application itself is not packaged as part of the client. All application changes are downloaded and
updated automatically, just like any other Magic RIA application. When you want to upgrade the core client
version (i.e. for a newer Magic release), you should rebuild the client and redistribute it to the devices.
Magic Software Enterprises Ltd., 5 Haplada Street, Or-Yehuda 60218, Israel
Tel: +972 (0)3 538 9292 | Fax: +972 (0)3 538 9333, +972 (0)3 538 9393 | [email protected] | www.magicsoftware.com
7
Installing and running the Travel Demo application Please follow these instructions carefully for installing the demo application included with this release.
1. Follow the above installation instructions for setting up the uniPaaS RIA server and the build tool
environment.
2. From the package zip file, extract the unipax folder into any location.
3. On IIS, create a virtual folder named images, pointing to the images folder in the unipax folder that
you just extracted.
4. Create a new database entry as follows:
5. Make sure that the images Magic logical name is pointing to the full web URL of the images virtual
directory. Make sure that the IIS user has sufficient permissions for this folder.
6. Still on IIS, create (or modify) two new MIME types (so that you can install the application Over-the-
Air):
.cod = application/vnd.rim.cod
.jad = text/vnd.sun.j2me.app-descriptor
7. Modify the execution.properties configuration file to use the new unipax application. The public
program name is mobile. Make sure that you use the correct settings for the requester and server,
according to the uniPaaS RIA server settings.
Magic Software Enterprises Ltd., 5 Haplada Street, Or-Yehuda 60218, Israel
Tel: +972 (0)3 538 9292 | Fax: +972 (0)3 538 9333, +972 (0)3 538 9393 | [email protected] | www.magicsoftware.com
8
8. Run the build tool. This will create two folders under the output folder (OverTheAir and Desktop).
9. On IIS, create a new virtual folder named install pointing to the OverTheAir folder in the output
folder. Make sure that the IIS user has sufficient permissions for this folder.
10. Run the Magic RIA server. You can open the application in the Studio and run the project.
11. On the BlackBerry, using the web browser, open the location where you created the client. Typically,
this location would be similar to http://localhost/install/TravelDemo.jad. You will be asked to
confirm the installation of the client. The installation will install an icon for the default download
folder.
12. Open the installed application on the BlackBerry.
Magic Software Enterprises Ltd., 5 Haplada Street, Or-Yehuda 60218, Israel
Tel: +972 (0)3 538 9292 | Fax: +972 (0)3 538 9333, +972 (0)3 538 9393 | [email protected] | www.magicsoftware.com
9
Travel Demo application walkthrough The travel demo application is a showcase for a simple Enterprise Travel Management System with a mobile
front-end. The demo application has two interfaces: one for Desktop RIA deployment and the other for
BlackBerry RIA deployment.
The travel demo application supports multiple device resolutions and was tested on devices using BlackBerry
OS 5, OS 6 and OS 7, with touch screens or with keyboard only.
1. From the BlackBerry desktop, run the Magic Travel Demo application.
2. Enter the user credentials. The default user name is [email protected]. The default password is the
letter “a”.
Magic Software Enterprises Ltd., 5 Haplada Street, Or-Yehuda 60218, Israel
Tel: +972 (0)3 538 9292 | Fax: +972 (0)3 538 9333, +972 (0)3 538 9393 | [email protected] | www.magicsoftware.com
10
3. Browse through the list of travel plans scheduled for Joe. Press Enter or click the Trackpad to view a
specific travel.
4. You can view Joe’s profile by selecting from the menu.
Magic Software Enterprises Ltd., 5 Haplada Street, Or-Yehuda 60218, Israel
Tel: +972 (0)3 538 9292 | Fax: +972 (0)3 538 9333, +972 (0)3 538 9393 | [email protected] | www.magicsoftware.com
11
5. When selecting a travel plan, you can view and browse the travel segments (flights, car rentals,
hotels). Selecting a specific travel segment by pressing Enter or clicking the Trackpad will show the
travel segment details.
6. Watch the different travel segment types (Flights, Hotels, Car rental).
Magic Software Enterprises Ltd., 5 Haplada Street, Or-Yehuda 60218, Israel
Tel: +972 (0)3 538 9292 | Fax: +972 (0)3 538 9333, +972 (0)3 538 9393 | [email protected] | www.magicsoftware.com
12
7. For each travel segment, you can view comments.
8. For flight segments, you can search for an airport from a popup dialog box.
Magic Software Enterprises Ltd., 5 Haplada Street, Or-Yehuda 60218, Israel
Tel: +972 (0)3 538 9292 | Fax: +972 (0)3 538 9333, +972 (0)3 538 9393 | [email protected] | www.magicsoftware.com
13
The application runs properly on devices with multiple resolutions by utilizing “Placement” capabilities.
320x240 (OS5) 480x360 (OS6)
640x480 (OS7)
Magic Software Enterprises Ltd., 5 Haplada Street, Or-Yehuda 60218, Israel
Tel: +972 (0)3 538 9292 | Fax: +972 (0)3 538 9333, +972 (0)3 538 9393 | [email protected] | www.magicsoftware.com
14
And using the same feature (Placement), it can run properly in landscape or portrait mode.