Onyx UI library

Overview

Onyx is a UI library for the Enyo 2.0 JavaScript framework. Onyx includes a variety of commonly used widgets, such as toolbars, text input fields, buttons, check boxes, progress bars, and so on. You can use the widgets from the Onyx UI library to build BlackBerry WebWorks applications for the BlackBerry 10 platform.

Demonstrating the Onyx widgets using the Onyx Sampler application

To demonstrate a collection of widgets from the Onyx UI library on BlackBerry 10, we will use the Onyx Sampler application. If you already have an application built with Enyo 2.0, adapt the following instructions as necessary to port your application to BlackBerry 10. In either case, here are the necessary activities:
  • Incorporate the Enyo core files and the necessary libraries with the application source files.
  • Build a BlackBerry WebWorks application from the application source files.
  • Load the BlackBerry WebWorks application on BlackBerry 10.

Obtain the OnyxSampler source files

  1. Download the OnyxSampler app source files from the following location: https://github.com/timwindsor/EnyoJS-on-BlackBerry.
  2. Extract the contents of the compressed file at a location of your choice.
  3. From the extracted files, navigate to the following location:
    \Enyo-2.0-OnyxSampler\lib\onyx\examples\
  4. Copy the OnyxSampler folder to a convenient location (for example, C:\OnyxSampler).

Incorporating the Enyo core files and the necessary libraries

The OnyxSampler folder contains the application's source code. To deploy the app, we will incorporate the Enyo core files, and other libraries that the source code refers to, in the OnyxSampler folder. One of the ways you can do this is to use Enyo Bootplate. Enyo Bootplate contains the latest release of Enyo core files and the most common libraries. We also use the icon file available in Enyo Bootplate. Here are the steps to accomplish all of this:

  1. Download the Enyo Bootplate (bootplate-<x.x.x>.zip) from the following location: http://enyojs.com/get-enyo/.

    Where <x.x.x> denotes the version of Enyo.

  2. Extract the contents of the compressed file to a location of your choice.
  3. Copy the enyo and lib folders and the icon.png file from the extracted content into the OnyxSampler folder.
  4. In the OnyxSampler folder, edit the index.html file as follows:
    1. Locate the index.html file and open it in any text editor.
    2. To update the reference to the Enyo core files, find the <script> element with the attribute src="../../../../enyo/enyo.js" and replace it with src="./enyo/enyo.js".

      The updated <script> element appears as follows:

      <script src="./enyo/enyo.js" type="text/javascript"></script>
    3. To update the reference to the Onyx UI library, find the <script> element with the attribute src="../../../onyx/package.js" and replace it with src="./lib/onyx/package.js".

      The updated <script> element appears as follows:

      <script src="./lib/onyx/package.js" type="text/javascript"></script>
    4. To update the reference to the fittable package in the layout library, find the <script> element with the attribute src="../../../layout/fittable/package.js" and replace it with src="./lib/layout/fittable/package.js".

      The updated <script> element appears as follows:

      <script src="./lib/layout/fittable/package.js" type="text/javascript"></script>
    5. Save the file and exit the text editor.
  5. In the OnyxSampler folder, in the enyo subfolder, delete the minify, samples, and tools folders.

Further reading

Building a BlackBerry WebWorks application package

A BlackBerry WebWorks application for BlackBerry 10 is packaged into a file with a .bar extension. The BlackBerry WebWorks Packager (bbwp) is a command-line tool that generates a .bar file from a .zip file, and it is included with the BlackBerry 10 WebWorks SDK. The .zip file is a BlackBerry WebWorks application archive file. It contains your application source files and a configuration file named config.xml (BlackBerry WebWorks configuration file).

Building a BlackBerry WebWorks application from your source files involves the following activities:
  1. Creating a BlackBerry WebWorks configuration file (config.xml).
  2. Creating a BlackBerry WebWorks application archive (.zip file).
  3. Generating a BlackBerry Archive (.bar file).

Create a BlackBerry WebWorks configuration file (config.xml)

In a text editor of your choice (for example, Notepad++), do the following:
  1. Copy the following XML code and paste it into a blank text file:
    <?xml version="1.0" encoding="UTF-8"?>
<widget xmlns="http://www.w3.org/ns/widgets"
		xmlns:rim="http://www.blackberry.com/ns/widgets"
		version="2.0.0.0" id="OnyxSampler">
	<name>Onyx Sampler</name>
	<author>Enyo 2.0</author>
	<content src="index.html"/>
	<icon src="icon.png"/>
</widget>

    All the elements are required except the <icon> element.

  2. Save the file as config.xml in the OnyxSampler folder.

Create a .zip file

In a file archiver of your choice (for example, 7-Zip), do the following:
  1. Select the contents of the OnyxSampler folder.
  2. Using the contents of the folder, create a .zip archive with the name OnyxSampler.zip.
  3. Save the OnyxSampler.zip file to the OnyxSampler folder.

Make sure that you create the .zip file from the contents of the OnyxSampler folder and not from the folder itself. The .zip file must have the config.xml file at the root level, not in a subfolder.

Generate a .bar file

Before you begin:

To complete this task, you must have the BlackBerry 10 WebWorks SDK installed on your computer. You can download the SDK from the following location: http://developer.blackberry.com/html5/download/

  1. At the command prompt, change your directory to the location where you installed the BlackBerry 10 WebWorks SDK. For example, in Windows, the default location is:
    C:\Program Files\Research In Motion\<BlackBerry 10 WebWorks SDK x.x.x.x>
    Where <x.x.x.x> denotes the version of the SDK that you installed.
  2. Type the following command:
    bbwp C:\OnyxSampler\OnyxSampler.zip -o C:\OnyxSampler\bb10build
    If the build process is completed successfully, two new folders should appear in the OnyxSampler folder: device and simulator, each containing the OnyxSampler.bar file.

Further reading

Loading a BlackBerry WebWorks application on BlackBerry 10

The blackberry-deploy tool is a command line tool available with the BlackBerry 10 WebWorks SDK for loading your app on BlackBerry 10. You can use this tool to load your app on a simulator or a device.

The instructions in this section show how to package an app and load it on a simulator for the BlackBerry 10 platform. To load your app on a BlackBerry 10 device, you must sign your app or use a debug token. Links to detailed information on how to sign apps or use debug tokens is provided below.

Load your application on a simulator

Before you begin

You must have a simulator for the BlackBerry 10 platform installed and running with the development mode enabled. You can download a simulator from the following location: http://developer.blackberry.com/develop/simulator/index.html
  1. At the command prompt, in the folder where you installed the BlackBerry 10 WebWorks SDK, navigate to the dependencies\tools\bin folder.
    For example, if the SDK is installed in the default location in Windows, type the following command:
    cd "C:\Program Files\Research In Motion\BlackBerry 10 WebWorks SDK <x.x.x.x>\dependencies\tools\bin"
    Where <x.x.x.x> denotes the version number of the SDK that you installed.
  2. Run the blackberry-deploy tool with the installApp option and specify the IP address of your simulator and the location of your .bar file:
    blackberry-deploy -installApp -device <Simulator IP address> -package <Full path of the .bar file>
    For example, if the IP address of the simulator is 192.0.2.124, we use the following command to load the OnyxSampler app: 
    blackberry-deploy -installApp -device 192.0.2.124 -package C:\OnyxSampler\bb10build\simulator\OnyxSampler.bar

    If you set a password on the simulator, you must specify the password using the password option -password <your password>

Further reading