Please note that as of October 24, 2014, the Nokia Developer Wiki will no longer be accepting user contributions, including new entries, edits and comments, as we begin transitioning to our new home, in the Windows Phone Development Wiki. We plan to move over the majority of the existing entries. Thanks for all your past and future contributions.

How to create a new Component for the Guarana UI Library

From Wiki
Jump to: navigation, search
Article Metadata
Code ExampleArticle
Created: jappit (20 Nov 2009)
Last edited: hamishwillee (05 Jul 2012)
Featured Article
21 Feb

This article shows all the steps involved in creating a new Component from scratch for the Nokia WRT Guarana UI Library.

Guarana ui new component.png

The Component built is this article is also visible on the Guarana UI online Components Browser.



The Guarana UI Library is a jQuery-Based UI Library for Nokia WRT, that provides a full set of Components ready to be used within Web Runtime widgets.

Guarana UI is structured into Components: User Interface elements that fulfill a specific function. Some examples include: Date, Rating and Progress Bar.

The Guarana UI structure allows to create new Components, by extending the Category:Web Apps base class. The Category:Web Apps base class represents a common base for all Guarana UI Components, providing basic and utility functions that manage event handling, vibration control and loading management of the Components.

Component files Structure

A Guarana UI Component is typically composed by:

  • 1 JavaScript file, placed in the "<GUARANA_BASE_PATH>/src/" folder
  • 1 CSS file, placed in the "<GUARANA_BASE_PATH>/themes/nokia/base/" folder
  • optionally, 1 or more images placed in the "<GUARANA_BASE_PATH>/themes/nokia/base/images/" folder

The Guarana UI Build processes

Before starting to create the new Component, it is necessary to download and uncompress the Full Guarana UI Package, available here: Guarana UI Full Package.

The Full Package ships with all the source files of the Guarana UI Library, and includes the build files necessary to create custom Library versions. To have a detailed overview of the Guarana UI folders and build process, check out the Guarana UI Overview.

Note: In this article, <GUARANA_BASE_PATH> refers to the complete path where the Guarana UI Full Package was uncompressed

Setup the Component source files

The following sections describe how to perform the setup steps for a new Guarana UI Component, here named TestComponent. The involved steps are:

  • creating the Component skeleton in the Guarana UI Full Package
  • build and move the lib and themes folder to an empty Web Runtime widget

Create an empty Web Runtime project

Before starting, create an empty Web Runtime project: it will be used to write and test the actual Component's code. You can do this manually, or by using the available Web Runtime IDE's Plugins.

Setup the Component skeleton structure

Now let's start, by creating the empty source files for the new TestComponent. These will be:

  • testcomponent.js: place this empty file in the "<GUARANA_BASE_PATH>/src" folder
  • testcomponent.css: place this empty file in the "<GUARANA_BASE_PATH>/themes/nokia/base/" folder

Now, it is necessary to tell the Guarana UI Library that these files exist. To do this, open the "<GUARANA_BASE_PATH>/src/defaults.js" file, and add this JavaScript code, just after all the other Components, as properties of the window.NOKIA_DEFAULTS.modules object:

* Test Component

'testcomponent': {
getPath: function() { return NOKIA_PATH_JAVASCRIPT + 'testcomponent.js'; },
requires: ['widget', 'testcomponent-css']
'testcomponent-css': {
getPath: function() { return NOKIA_PATH_STYLE_ROOT + 'testcomponent.css'; },
type: 'css',
requires: ['base-css']

These 2 properties allow Guarana UI to know that new resources exist, and specify the dependencies of each of them. Most of the Components usually require only the specified dependencies, but it's possible to change them accordingly to different needs.

Before proceeding, perform the same modifications to the "<GUARANA_BASE_PATH>/build/build/js/defaults.js" file.

Build Guarana UI and move resources

Now that the skeleton files are ready, it is possible to build Guarana UI by using the standard build process. Just go into the "<GUARANA_BASE_PATH>/build/" folder and, from command-line, call:


Once built, move the "<GUARANA_BASE_PATH>/build/Guarana/lib/" and "<GUARANA_BASE_PATH>/build/Guarana/themes/" to the empty Web Runtime widget created before.

Before proceeding, check that the Component empty files were actually built. If so, they should be located at these paths:

  • "<GUARANA_BASE_PATH>/build/Guarana/lib/testcomponent.js"
  • "<GUARANA_BASE_PATH>/build/Guarana/themes/nokia/base/testcomponent.css"

Writing the Component code

The following sections show how to write the actual Component's code.

The Component JavaScript skeleton

The very-basic Component is composed by just one function, that takes care of initializing the Component itself:

(function() {
Nokia.TestComponent = Nokia.Widget.extend({
initialize: function(options) {
// initialize the Component

Some other functions and properties are also usually defined, and they are:

  • the _create() function, that takes care of creating the Component's DOM structure and of defining all the event handlers
  • the Styles property, that holds the names of CSS classes used by the Component

So, a more complete Component will be the following one:

(function() {
Nokia.TestComponent = Nokia.Widget.extend({
initialize: function(options) {
// initialize the Component
_create: function() {
// create the Component DOM structure and define events
Styles: {
// define the main CSS styles classes used by the Component

Define the Component DOM structure

The TestComponent built in this article has to show a message, and so it is possible to use the following simple DOM structure:

<div class="test-component">
<p class="test-component-message">
Hello World!

The Component's CSS classes

Since the Component uses 2 CSS classes, it is possible to use the Component's Styles property to store their names, as shown below:

Styles: {
testComponent: 'test-component',
message: 'test-component-message'

Those classes will be defined in the Component's CSS file, testcomponent.css. Some simple rules are the following:

.test-component {
margin: .5em;
padding: .5em;
background: #dddddd;
border: 4px solid #aaaaaa;
.test-component-message {
color: #666666;

Initializing the Component

The initialization is actually the most important part of the Component, as it has to:

  • initialize the Component's properties, by using the passed options together with the default ones. The following code shows how to define some default options (in this case, a default message), and how to add to these options the ones passed to the Component:
var defaults = {
message: "Hello World!"
instance.options = jQuery.extend(defaults, options);
  • get a reference to the Component's placeholder DOM element:
instance.element = jQuery( instance.options.element );
  • call the Widget super-class initialization function:
instance._super.apply(instance, [instance.options]);
  • register the component. This is done with a call to the "registerData()" function:
  • create the DOM structure. This is usually done from a separate function (usually the "_create" one), so the initialize() function just calls that:
  • fire the 'create' callback, to notify the finish of the initialization process:

The complete initialize() function is the following one:

initialize: function(options) {
var instance = this;
var defaults = {
message: "Hello World!"
instance.options = jQuery.extend(defaults, options);
instance.element = jQuery( instance.options.element );
instance._super.apply(instance, [instance.options]);

Create the DOM structure

Let's take back the Component's DOM structure: it is now necessary to create it via JavaScript, defining the necessary event handlers, and using the Styles property to assign the right CSS class to the various elements. The following code shows how this can be performed:

_create: function() {
var instance = this;
var options = instance.options;
var element = instance.element;
var Styles = instance.Styles;
element.each(function(i, el) {
Nokia.util.addClass(el, Styles.testComponent);
instance.hello = Nokia.dom.parseHTML('<p class="' + Styles.message + '">' + this.options.message + '</p>');

In the above code, it is possible to see how to use the Component's "options" property to retrieve the message to display.

Add some interactivity to the Component

In order to add some interactivity, let's define a function that allows to change the displayed message. This function is visible below:

setValue: function(html)
var instance = this;

Using the component

The component is now ready for use, and to actually create a TestComponent within a Web Runtime widget the following steps have to be performed:

<!-- Themeroller CSS -->
<link rel="stylesheet" href="themes/themeroller/default-theme/Themeroller.css" type="text/css" media="screen">
<!-- Specific Theme/Resolution CSS -->
<link rel="stylesheet" href="themes/nokia/ext-theme/default/360x640/custom.css" type="text/css" media="screen">
  • Include the JavaScript dependencies:
<!-- jQuery file -->
<script src="/lib/jquery/jQuery.js" type="text/javascript" charset="utf-8"></script>
<!-- Guarana file -->
<script src="/lib/Guarana.js" type="text/javascript" charset="utf-8"></script>
  • Define a placeholder DOM element in the widget's HTML code:
<div id="testcomponent01"></div>
  • Call the "Nokia.use" function to tell Guarana UI that you need to use the new component. Details about the Nokia Loader are available here: Nokia Loader. Before calling the Nokia Loader, it is necessary to define the 2 Guarana UI PATH variables, to specify where its folders are located:
NOKIA_PATH_STYLE_ROOT = 'themes/nokia/base/';
Nokia.use('testcomponent', init);
  • When the Component resources will be available, the init() function is called. Within the init() function, it is so possible to create an instance of the newly created TestComponent:
function init()
var testComponent1 = new Nokia.TestComponent({
element: '#testcomponent01',
message: "I'm a custom message!",
create: function() {
alert('test component created');

If all goes well, an alert message with the "test component created" message should be displayed, just after the Component creation.

Finalize the Component

Now that the Component is ready, it is possible to move its resources back to the Guarana UI Full Package folders, overwriting the empty files created at the beginning.

Note: if the Component also uses images (e.g.: referenced by the Component's CSS file), it is necessary to move them also to the Guarana UI folders. In case of images, the folder to use is the "<GUARANA_BASE_PATH>/themes/nokia/base/images/".

Once the Component's files are copied back to the Guarana UI folders, it is possible to launch a new build process, that will optimize and compress the Component's code. Done that, everything is ready to use and distribute the new Component.

Links and Resources

This page was last modified on 5 July 2012, at 01:53.
62 page views in the last 30 days.