×
Namespaces

Variants
Actions
(Difference between revisions)

News Ticker JavaScript component for Web Runtime

From Nokia Developer Wiki
Jump to: navigation, search
gaba88 (Talk | contribs)
hamishwillee (Talk | contribs)
m (Hamishwillee - Bot update - Fix metadata etc)
 
(4 intermediate revisions by one user not shown)
Line 1: Line 1:
{{ReviewerApproved}}
+
[[Category:Code Examples]][[Category:Symbian Web Runtime]][[Category:Mobile Design]][[Category:How To]]
[[Category:Code Examples]][[Category:Web Runtime (WRT)]][[Category:Mobile_Design]][[Category:How To]]
+
{{Abstract|This article shows how to build and use an animated News Ticker component in Symbian Web Runtime widgets. The News Ticker design pattern is described in detail in this Nokia Developer Wiki Article: [[Mobile Design Pattern: News Ticker]].}}
This article shows '''how to build and use an animated News Ticker component''' in '''Web Runtime widgets'''. The '''News Ticker design patter''' is described in detail in this Forum Nokia Wiki Article: [[Mobile Design Pattern: News Ticker]].
+
  
[[Image:Wrt_newsticker_widget.png]]
+
{{ArticleMetaData <!-- v1.2 -->
 +
|sourcecode= [[Media:Wrt NewsTicker component.zip]] [[Media:NewsTickerWidget.zip]] [[Media:Wrt NewsTicker component.zip]]
 +
|installfile= <!-- Link to installation file (e.g. [[Media:The Installation File.sis]]) -->
 +
|devices= <!-- Devices tested against - e.g. ''devices=Nokia 6131 NFC, Nokia C7-00'') -->
 +
|sdk= <!-- SDK(s) built and tested against (e.g. [http://linktosdkdownload/ Qt SDK 1.1.4]) -->
 +
|platform= <!-- Compatible platforms - e.g. Symbian^1 and later, Qt 4.6 and later -->
 +
|devicecompatability= <!-- Compatible devices e.g.: All* (must have internal GPS) -->
 +
|dependencies= <!-- Any other/external dependencies e.g.: Google Maps Api v1.0 -->
 +
|signing= <!-- Signing requirements - empty or one of: Self-Signed, DevCert, Manufacturer -->
 +
|capabilities= <!-- Capabilities required by the article/code example (e.g. Location, NetworkServices. -->
 +
|keywords= <!-- APIs, classes and methods (e.g. QSystemScreenSaver, QList, CBase -->
 +
|language= <!-- Language category code for non-English topics - e.g. Lang-Chinese -->
 +
|translated-by= <!-- [[User:XXXX]] -->
 +
|translated-from-title= <!-- Title only -->
 +
|translated-from-id= <!-- Id of translated revision -->
 +
|review-by= <!-- After re-review: [[User:username]] -->
 +
|review-timestamp= <!-- After re-review: YYYYMMDD -->
 +
|update-by= <!-- After significant update: [[User:username]]-->
 +
|update-timestamp= <!-- After significant update: YYYYMMDD -->
 +
|creationdate= 20090609
 +
|author= [[User:Jappit]]
 +
}}
 +
 
 +
[[File:Wrt newsticker widget.png]]
  
 
==NewsTicker component: how to use it==
 
==NewsTicker component: how to use it==
 
The News Ticker component presented in this article can be used in any Web Runtime widget, by following these steps:
 
The News Ticker component presented in this article can be used in any Web Runtime widget, by following these steps:
* '''Include the NewsTicker.js JavaScript file''' in your Widget (available for download here: [[Media:Wrt_NewsTicker_component.zip]])
+
* '''Include the NewsTicker.js JavaScript file''' in your Widget (available for download here: [[Media:Wrt NewsTicker component.zip]])
 
<code javascript>
 
<code javascript>
 
<script language="javascript" type="text/javascript" src="NewsTicker.js"></script>
 
<script language="javascript" type="text/javascript" src="NewsTicker.js"></script>
Line 271: Line 293:
 
The following files, related to this article, are available for download:
 
The following files, related to this article, are available for download:
 
* A sample Web Runtime widget using the News Ticker component: [[Media:NewsTickerWidget.zip]]
 
* A sample Web Runtime widget using the News Ticker component: [[Media:NewsTickerWidget.zip]]
* The News Ticker component source code: [[Media:Wrt_NewsTicker_component.zip]]
+
* The News Ticker component source code: [[Media:Wrt NewsTicker component.zip]]

Latest revision as of 08:50, 7 May 2012

This article shows how to build and use an animated News Ticker component in Symbian Web Runtime widgets. The News Ticker design pattern is described in detail in this Nokia Developer Wiki Article: Mobile Design Pattern: News Ticker.

Article Metadata
Code ExampleArticle
Created: jappit (09 Jun 2009)
Last edited: hamishwillee (07 May 2012)

Wrt newsticker widget.png

Contents

[edit] NewsTicker component: how to use it

The News Ticker component presented in this article can be used in any Web Runtime widget, by following these steps:

<script language="javascript" type="text/javascript" src="NewsTicker.js"></script>
  • Define a HTML node, in your Widget HTML code, to contain the News Ticker component:
<body>
[...]
<div id="ticker_container"></div>
[...]
</body>
  • Define an Array containing the news titles to be displayed in the News Ticker:
var newsArray = new Array(
"Flash Lite Applications: Kero Mobile and KiTwitts, major development differences!",
"Web Runtime JavaScript battery and network signal components",
"Great News from Symbian Foundation:Opening the world of Infinite possibilities"
);
  • Create a NewsTicker instance with these parameters:
    • the news titles array
    • the parent HTML node
    • the ticker width
    • the ticker height

In order to support display rotations, it is recommended to use widths expressed in percentage (e.g.: 90%).

var ticker = new NewsTicker(
newsArray,
document.getElementById('ticker_container'),
'90%',
'30px'
);
  • Start the News Ticker, by calling its start() method:
ticker.start();

[edit] NewsTicker component implementation

The News Ticker component will be implemented by following these steps:

  • a costructor, that defines the component properties
  • a method (init()) that initializes the component's DOM structure
  • a method (start()) that actually starts the component
  • a method (animate()) that performs the news title animation, letting the text scroll from right to left
  • two methods (startAnimation and stopAnimation()) that will start and stop, respectively, the news ticker animation
  • a method (showNextNews()) that shows the next available news inside the news ticker
  • a method (setNewsClickHandler()) that allows to define a handler function to be called when the user clicks on the news ticker
  • a method (setAnimationStepPixels()) to modify the speed of the scrolling animation

[edit] NewsTicker constructor

The NewsTicker constructor is implemented as follows, accepting 4 parameters:

  • the news titles array
  • the parent HTML node
  • the width of the news ticker
  • the height of the news ticker

It defines the properties shown in code, whose purpose is explained in the relative comment, and then calls the init() method, that will care of building up the component's DOM structure.

function NewsTicker(newsArray, parentElement, tickerWidth, tickerHeight)
{
/* ticker animation step (in pixels) */
this.animationStep = 2;
 
/* DOM element containing the currently shown news title */
this.newsElement = null;
 
/* empty DOM element used to calculate the visible ticker width */
this.emptyElement = null;
 
/* array containing the news titles */
this.newsArray = newsArray;
 
/* index of the news currently shown */
this.currentNewsIndex = 0;
 
/* ID of the animation returned by setInterval() */
this.animationInterval = null;
 
/* news click handler */
this.newsClickHandler = null;
 
/* call to the DOM initialization method */
this.init(parentElement, tickerWidth, tickerHeight);
}

[edit] Building DOM structure

The init() method builds up the DOM structure of the component, designed as follows:

  • an outer DIV element, with the desired width and height. This element has the overlow CSS property equal to hidden, to hide the text overflowing the ticker width
  • an inner DIV element, that will actually contain the news title text, with these characteristics:
    • absolute positioning that allows to perform the text scrolling animation
    • white-space: nowrap CSS property, that will allow the text to be displayed in a single line, even if longer than the available space
  • an empty DIV element, that will be used to calculate the available space for the news' titles

Done this, the component DOM element is appended to the parent element passed as argument, and is initialized with the title of the first available news.

NewsTicker.prototype.init = function(parentElement, tickerWidth, tickerHeight)
{
var mainElement = document.createElement('div');
mainElement.className = NewsTicker.cssClass;
mainElement.style.width = tickerWidth;
mainElement.style.height = tickerHeight;
mainElement.style.overflow = 'hidden';
mainElement.style.position = 'relative';
 
var fakeElement = document.createElement('div');
mainElement.appendChild(fakeElement);
this.emptyElement = fakeElement;
 
var textElement = document.createElement('div');
textElement.style.position = 'absolute';
textElement.style.whiteSpace = 'nowrap';
 
this.newsElement = textElement;
 
mainElement.appendChild(textElement);
 
parentElement.appendChild(mainElement);
 
textElement.innerHTML = this.newsArray[0];
}

[edit] Animating the news ticker

In order to display the whole news title text, a right-to-left scrolling animation will be implemented. The following animate() method takes care of performing a single animation step and, if the right bound of the news text is already visible, it calls the showNextNews() method (implemented later) to display the following news. A small delay (2 seconds) is used before showing the following news, to allow the user to easily read the whole news title.

NewsTicker.prototype.animate = function()
{
var textLeft = parseInt(this.newsElement.offsetLeft);
var textWidth = parseInt(this.newsElement.offsetWidth);
 
if(textLeft + textWidth > this.emptyElement.offsetWidth)
{
var newLeft = textLeft - this.animationStep;
 
this.newsElement.style.left = newLeft + 'px';
}
else
{
this.stopAnimation();
 
var self = this;
 
setTimeout(
function()
{
self.showNextNews();
},
2000
);
}
}

[edit] Showing the next available news

When a single news title reaches the end of its animation, then it has to be replaced with the following one. This will be done by the following showNextNews() method, that takes care of:

  • resetting the news DOM element position (because of the animation movement)
  • replacing the old news title with the new one
  • restarting the news scrolling animation after a small delay (2 seconds) to allow the user to easily read the first part of the news title
NewsTicker.prototype.showNextNews = function()
{
this.currentNewsIndex = (this.currentNewsIndex + 1) % this.newsArray.length;
 
this.newsElement.style.left = '0px';
 
this.newsElement.innerHTML = this.newsArray[this.currentNewsIndex];
 
var self = this;
 
setTimeout(
function()
{
self.startAnimation();
},
2000
);
}

[edit] Managing the news ticker animation

In order to manage and perform the news ticker animation, the setInterval() method is used. The following methods will respectively start and stop the animation:

/**
* Starts the news ticker animation
*/

NewsTicker.prototype.startAnimation = function()
{
if(this.animationInterval == null)
{
var self = this;
 
this.animationInterval = setInterval(
function()
{
self.animate();
},
100
);
}
}
 
/**
* Stops the news ticker animation
*/

NewsTicker.prototype.stopAnimation = function()
{
if(this.animationInterval != null)
{
clearInterval(this.animationInterval);
 
this.animationInterval = null;
}
}

[edit] Starting the component

As seen from the first part of this article, after having instantiated a NewsTicker, it is necessary to start it via the start() method. The start() method, implemented as follows, uniquely calls the startAnimation() method, with a delay of 2 seconds, to start the news ticker animation.

NewsTicker.prototype.start = function()
{
var self = this;
 
setTimeout(
function()
{
self.startAnimation();
},
2000
);
}

[edit] Handling user interaction

In order to allow user interaction on the News Ticker component, a handler function must be called. Specifically, we want the component to call a handler function when the user clicks on the component itself, passing the currently shown news' index as argument. This is done by the following setNewsClickHandler() function:

NewsTicker.prototype.setNewsClickHandler = function(clickHandler)
{
this.newsClickHandler = clickHandler;
 
if(clickHandler != null)
{
var self = this;
 
this.newsElement.onclick = function()
{
self.newsClickHandler(self.currentNewsIndex);
}
}
else
{
this.newsElement.onclick = undefined;
}
}

[edit] Setting the ticker speed

In order to have a faster or slower News Ticker instances, it is possible to modify the animationStep property, that defines the number of scrolled pixels for each animation step. The following setAnimationStepPixels() will allow this:

NewsTicker.prototype.setAnimationStepPixels = function(stepPixels)
{
if(stepPixels < 0)
stepPixels = 1;
 
this.animationStep = stepPixels;
}

[edit] Downloads

The following files, related to this article, are available for download:

This page was last modified on 7 May 2012, at 08:50.
78 page views in the last 30 days.
×