×
Namespaces

Variants
Actions
Revision as of 13:41, 2 May 2011 by isalento (Talk | contribs)

Nokia Asha web apps - FAQ

From Nokia Developer Wiki
Jump to: navigation, search
Featured Article
17 Apr
2011

This article provides a guide to Series 40 web apps. The article answers various frequently asked questions on how to use Series 40 web apps. Series 40 web apps offer an easy entry point to mobile app development where one can utilize their web developer skills to create content with HTML, CSS, and JavaScript code.

Contents


Getting started


How do I get started?

What do I need to develop and test Series 40 web apps?

Support facilities


Where can I find documentation?

Series 40 web apps documentation on the Forum Nokia website

Where can I find example apps?

How do I use the support channels?

How do I report bugs?

Development


What is the user agent string for the Ovi Browser / Series 40 web apps clients

Example user agent string: Mozilla/5.0 (Series40; NokiaX3-02/05.65; Profile/MIDP-2.1 Configuration/CLDC-1.1) Gecko/20100401 S40OviBrowser/1.0.0.9.17.

Architecture

How do Ovi Browser / Series 40 web apps differ from conventional browser and web app execution environments

Ovi Browser is a distributed user agent. The browser client renders content compressed and formatted by the Ovi Browser Proxy.

For developers this means that JavaScript is executed in the proxy rather than on the client.

This helps provide a web app experience in very affordable hardware that would have challenges running a full JavaScript stack.

Please read the Series 40 web apps - Platform overview document for more information.

Can I host my application code on my own server?

To some extent, yes.

You can create an app that redirects it's context to your own server, however in that case you cannot currently utilise Mobile Web Library calls to their full extent.

What is the biggest or recommended file size for Series 40 web apps?

There is a limit to the size of .wgt files that can be upload, it's currently set to 500kb.

Debugging and testing

How can I debug or log my application?

Web Apps Simulator (one of the Nokia Web Tools) provides server side logging of console.log() calls. Please see the simulator user guide for more information.

The first version of Series 40 web apps doesn't support logging or debugging in target hardware.

However, you can use a 3rd party logging solution such as log4javascript to flush logs to your own server script.

Tools

How do I go back from an external web resource in the simulator

  • Press the backspace key to go back one page in the history stack.
    • Note: The Back and Menu softkeys are not functional in the simulator.

JavaScript

What is MWL (Mobile Web Library)?

MWL is a JavaScript library provided by Nokia for Series 40 web apps.

Direct MWL calls are the only JavaScript that will be executed on the client, thus you will find it useful to implement functionality such as view switching or timer triggered operations.

  • the MWL is automatically injected to all Series 40 web apps - you don't need to add it to your code.
  • provides functions to modify the CSS properties of DOM elements, set locally executed timers, and break out of the web app context to remote URLs.

Get an MWL overview and full API documentation for Series 40 web apps in the Developer guide and API reference.

Can I use jQuery or other popular libraries?

In many cases, yes.

However keep in mind that JavaScript is executed on the server side and remember the limitations with functionality, such as lack of native JSON parsing and timers.

Can I use any off the shelf JavaScript?

Most off the shelf JavaScript will function, but keep in mind that any non-MWL call will be executed in the proxy and execution loops will cause a client-server roundtrip.

Some important omissions

  • Native JSON parsing is not supported. Use eval() to transform raw JSON data to live data.
  • JavaScript timers (setTimeout(), setInterval()) are not supported, since they do not fit into the distributed architecture of Ovi Browser / Series 40 web apps.
    • Use the MWL timer() function to work around this.

How to execute MWL calls locally on the client?

Rule of thumb: Tie MWL calls directly to DOM event handlers

  • Calls wrapped in custom JavaScript functions will always step to the server side.
       <head>
<script>
function showBox()
{
mwl.show('#box');
}
</script>
</head>
<body>
<!-- This click handler will execute locally -->
<a onclick="mwl.show('#box');">Right way</a>
 
<!-- This click handler will cause a server roundtrip,-->
<!-- since it's calling a non-MWL function-->
<a onclick="showBox();">Wrong way</a>
 
 
<div class="mybox" id="box"></div>
</body>

You can chain MWL and other JavaScript calls to, for example, modify displayable elements locally before stepping to the server side:

<!--Chains locally executed MWL CSS operations and-->
<!--a locally executed timer that triggers a server-side operated call (myajaxcall)-->
<a onclick="mwl.show('#el1');mwl.hide('#el2');mwl.timer('tmr', 10, 1, 'myajaxcall(\'http://api.com/get\')');">Chain action</a>

You can generate DOM elements with MWL event handlers in JavaScript also - this can be useful when generating new page structures from downloaded content, when you don't want to deal with massive raw HTML string operations.

var myEl = document.createElement('img');
myEl.setAttribute('onclick', 'mwl.toggleClass(\'#progress_anim\', \'progress_visible\');API.run(' + i + ');');


Pay extra attention on quotation marks, when attaching MWL event handlers in JavaScript.

document.getElementById("btn").innerHTML = "<div onclick=\'mwl.toggle(\"#tg1\");return false;\'>wrong</div>";
document.getElementById("btn2").innerHTML = "<div onclick=\"mwl.toggle(\'#tg1\');return false;\">right</div>";


Why is my code causing round trips to the server when JavaScript is executed?

See the answers above.

  • JavaScript wrapped in non-MWL calls will always step to the server for execution.
  • One good approach is to build a logic that downloads and generates fairly large DOM structures:
    • The DOM structure should then be split to visible and hidden parts that can be toggled between with direct locally executed MWL calls.
    • The RSS reader template in Nokia Web Tools is a good example of this approach.

APIs and features

Does Ovi Browser / Series 40 web apps environment support HTML5

The first version of Series 40 web apps doesn't have support for HTML5 features.

What CSS3 features are supported?

Animated 2D transitions of width, height, and margin properties are supported with the -webkit -prefix. Use MWL calls such as addClass to run animations on the client side.

More information is available in the Series 40 web apps - Developer guide and API reference

Rounded corners, gradients, and other CSS3 visual effects are not supported in first version of Series 40 web apps.

What URI schemes are supported?

http, https, tel

Can I call, or send sms or email?

Initiating calls with tel URI scheme is supported.

<a href="tel:+3581234567p123">Dial</a>
<a href="tel:+3581234567p123">Dial - then pause before sending a new number</a>
<a href="tel:+3581234567w123">Dial - then ask the user if he wants to send a new number</a>

Sms and email creation is not supported in the first release.

How do I playback or stream video or audio?

Current version of web apps enables you to launch video and audio playback using the native player on the device. However, the use case flow shows a screen prompting the user to start playback of the media file.

Example:

<a href="#" onclick="mwl.loadURL('http://www.my.example.video/video.mp4');">Play video</a>

Find information on the supported formats and codecs from web app compatible device specs at Forum Nokia

Embedding video files is not possible in the first version of web apps.

Functionality on the simulator differs from real devices, therefore it's recommended highly that multimedia functionality is tested on a device.

Can I create custom items for the Ovi Browser options menu?

Not in the first version of Series 40 web apps. You need to create your own menu with HTML.

Can I tie an event handler to the Ovi Browser Back-button?

Not in the first version of Series 40 web apps. You need to create a custom Back-button for navigation inside your app context.

How can I close my app from JavaScript code?

window.close() and the other options you might normally use aren't supported in the first release of Series 40 web apps. Apps are run in Ovi Browser context and users can exit the browser as they normally do.

How can I detect resolution or other client side parameters?

The first release of Series 40 web apps has a known issue, where the queries of items such as screen, window, and navigator object parameters return properties of the proxy server rather than the client.

For example, calling navigator.userAgent or window.innerWidth return the corresponding values from the proxy, not the client. This is a problem, since it makes it difficult to determine client side parameters for cross device UI layout creation.

Known Issue

You can hack your way around this by looking at the http request headers sent by your web app and received by a remote web server.

We have set up simple php scripts to get text and JSON output of your user agent string:

The server side scripts for the above are fairly simple and can be freely copied if required:

Apache server rewrites:

<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /
RewriteCond %{REQUEST_FILENAME} /js.*
RewriteRule js.(.*) /index.php?output=$1 [L]
</IfModule>

PHP:

<?php
// Read a GET parameter to determine the output format, if none specified, nothing is output
if (isset($_GET['output']) && $_GET['output'] != '') {
$show_markup = $_GET['output'];
}
 
// Preparing an Array with the User-Agent string. Might add more parameters in the future
if (isset($headers['User-Agent'])) {
$api_values['User-Agent'] = $headers['User-Agent'];
}
 
switch ( $show_markup ) {
case 'json':
header('Content-type: application/json');
echo json_encode($api_values);
break;
case 'xml':
// not implemented
break;
case 'text':
header('Content-type: text/plain');
echo $api_values['User-Agent'];
break;
}
?>

This is example JavaScript code to call the above mentioned URLs at logme.mobi and obtaining the real user agent string of the Ovi Browser client:

function handleResponse(content){
document.getElementById("ua").innerHTML = content;
}
 
function getLogMe(){
var xhr;
var myurl = "http://logme.mobi/js.text";
xhr = new XMLHttpRequest();
xhr.open("GET", myurl, true);
xhr.setRequestHeader("Cache-Control", "no-cache");
xhr.setRequestHeader("Pragma", "no-cache");
xhr.onreadystatechange = function(){
if (xhr.readyState == 4) {
if (xhr.status == 200) {
if (xhr.responseText != null) {
// Work with the response
handleResponse(xhr.responseText);
}
else {
// something is wrong
return '';
}
}
else {
// something is wrong
return '';
}
}
}
//send the request
xhr.send(null);
}

This would give you the real user agent string to play with, after which you can determine what device the browser is running on and, for example, apply a different landscape layout to the web app on devices that have landscape QVGA resolution.

Can I store data locally on the client?

Local storage isn't supported in the first version of Series 40 web apps.

You can use the preferences attribute of W3C Widget Interface to store application instance specific persistent data in the Ovi Browser proxy.

Do you provide an API to query user's location?

The first version of Series 40 web apps doesn't provide location APIs. A user agent IP lookup also returns the IP of the data centre of Ovi Browser Proxy through which the network traffic is routed.

Do you support device APIs?

Device APIs aren't supported in the first version of Series 40 web apps.

Do you support Flash?

There is no Flash support in Series 40 web apps / Ovi Browser.

Can Series 40 web apps integrate to device home screen?

Home screen integration isn't supported in the first version of Series 40 web apps.

Can I use a map API in Series 40 web apps?

Yes. Any map service that outputs static images (png, gif, jpeg) should do.

Ovi Maps Rendering API provides an easy to use REST interface for accessing, for example, map tiles.

Can I use an advertising API in Series 40 web apps

Nokia doesn't currently offer a publicly available Series 40 web apps optimised ad-solution.

3rd party mobile JavaScript ad-frameworks should work, but haven't been rigorously tested in this environment.

I need to integrate to Facebook and Twitter from my web app, how do I do it?

Current Series 40 web apps development offering doesn't contain frameworks for integrating to popular social networks.

Thus, you need to implement integration points yourself or use third-party frameworks.

Do you have a recommended UI library?

The first version of Series 40 web apps doesn't include a full UI library.

Porting

How do I port my existing web site?

Although Ovi Browser can render most web content well, it's recommended to optimise the content and layout sent to Ovi Browser clients, to do this for your website:

  • Familiarise yourself with this FAQ, the platform overview guide, and the best practices guides to understand the limitations in features such as JavaScript execution, CSS support, and event handling.
  • Keep in mind that Ovi Browser clients run in affordable mobile phones with QVGA screens in landscape or portrait resolution.
  • Detect Ovi Browser clients by looking for matches within the example UA string.

Can I create a redirecting launcher app that points to my existing website?

Yes, you can. To create the simplest possible packaged web app, just do a simple redirect in your JavaScript, for example:

document.location.href = "http://nokia.mobi";

However, remember that MWL will only be injected to the initial page of your application and MWL calls don't currently execute locally in the client if the code is hosted from your own server.

How do I port my existing Symbian WRT widget or other packaged web app?

Some things to check and remember:

  • Series 40 web apps use W3C widget packaging format, which is different from Symbian WRT.
  • As with porting between any other environments, API and feature differences exist. For example, Series 40 web apps don't currently support any device APIs.
  • JavaScript (except direct MWL calls) execute on the server, thus many apps with heavy client side logic, DOM manipulation, etc. would benefit from redesign of the code to optimise the need for server round trips.

In many cases, it's worthwhile considering redesigning your application rather than attempting to port.

Publishing

Where can I publish my app?

We're hard at work preparing Ovi Store readiness for Series 40 web apps. Please check for announcements of availability here.

964 page views in the last 30 days.
×