×
Namespaces

Variants
Actions
(Difference between revisions)

Using widget.preferences in Nokia Asha Web Apps

From Nokia Developer Wiki
Jump to: navigation, search
isalento (Talk | contribs)
(Isalento - - Troubleshooting)
hamishwillee (Talk | contribs)
m (Hamishwillee - Bot update - Fix metadata)
 
(7 intermediate revisions by 2 users not shown)
Line 1: Line 1:
[[Category:Series 40 Web Apps]]
+
[[Category:Nokia Asha Web Apps]][[Category:Files/Data]][[Category:Series 40]]
{{Abstract|This article explains how to store data using widget.preferences in Series 40 Web Apps }}  
+
{{Abstract|This article explains how to store data using {{Icode|widget.preferences}} in Nokia Asha Web Apps }}  
  
{{ArticleMetaData <!-- v1.2 -->
+
{{ArticleMetaData <!-- v1.3 -->
 
|sourcecode= <!-- Link to example source code e.g. [[Media:The Code Example ZIP.zip]] -->
 
|sourcecode= <!-- Link to example source code e.g. [[Media:The Code Example ZIP.zip]] -->
 
|installfile= <!-- Link to installation file (e.g. [[Media:The Installation File.sis]]) -->
 
|installfile= <!-- Link to installation file (e.g. [[Media:The Installation File.sis]]) -->
|devices= Nokia X3-02
+
|devices= Nokia X3-02
 
|sdk= <!-- SDK(s) built and tested against (e.g. [http://linktosdkdownload/ Qt SDK 1.1.4]) -->
 
|sdk= <!-- SDK(s) built and tested against (e.g. [http://linktosdkdownload/ Qt SDK 1.1.4]) -->
|platform= Series 40 Web Apps version 1.5
+
|platform= Nokia Asha Web Apps version 1.5
|devicecompatability=  All Series 40 devices supporting Web Apps
+
|dependencies= <!-- Any other/external dependencies e.g.: Google Maps Api v1.0 -->
|dependencies= <!-- Any other/external dependencies e.g.: Google Maps Api v1.0 -->  
+
|signing= <!-- Signing requirements - empty or one of: Self-Signed, DevCert, Manufacturer -->
|signing=<!-- Signing requirements - empty or one of: Self-Signed, DevCert, Manufacturer -->
+
|capabilities= <!-- Required capabilities for code (e.g. ID_CAP_LOCATION, ID_CAP_NETWORKING) -->
|capabilities= <!-- Capabilities required by the article/code example (e.g. Location, NetworkServices. -->
+
|keywords= widget.preferences
|keywords= widget.preferences
+
 
|language= <!-- Language category code for non-English topics - e.g. Lang-Chinese -->
 
|language= <!-- Language category code for non-English topics - e.g. Lang-Chinese -->
 
|translated-by= <!-- [[User:XXXX]] -->
 
|translated-by= <!-- [[User:XXXX]] -->
|translated-from-title= <!-- Title only -->  
+
|translated-from-title= <!-- Title only -->
 
|translated-from-id= <!-- Id of translated revision -->
 
|translated-from-id= <!-- Id of translated revision -->
|review-by=<!-- After re-review: [[User:username]] -->
+
|review-by= <!-- After re-review: [[User:username]] -->
 
|review-timestamp= <!-- After re-review: YYYYMMDD -->
 
|review-timestamp= <!-- After re-review: YYYYMMDD -->
 
|update-by= <!-- After significant update: [[User:username]]-->
 
|update-by= <!-- After significant update: [[User:username]]-->
 
|update-timestamp= <!-- After significant update: YYYYMMDD -->
 
|update-timestamp= <!-- After significant update: YYYYMMDD -->
|creationdate= 20120312
+
|creationdate= 20120312
|author= [[User:isalento]]  
+
|author= [[User:isalento]]
 +
<!-- The following are not in current metadata -->
 +
|devicecompatability= All Nokia Asha devices supporting Web Apps
 
}}
 
}}
  
Line 33: Line 34:
  
 
=== Declaring preference ===
 
=== Declaring preference ===
Preference key must always be declared in config.xml file, in Series 40 Web Apps, prior to use. Failing to do so does not cause immediate error, but values stored are not preserved and lost when Web App is re-started.  
+
Preference key must always be declared in config.xml file, in Nokia Asha Web Apps, prior to use. Failing to do so does not cause immediate error, but values stored are not preserved and lost when Web App is re-started.  
  
Declaring preference in config.xml:
+
Declaring preference in '''config.xml''':
 
<code xml>
 
<code xml>
 
<preference name="apikey"  
 
<preference name="apikey"  
Line 41: Line 42:
 
       readonly="true"/>
 
       readonly="true"/>
 
</code>
 
</code>
<tt>readonly</tt> is an optional argument, thus can be omitted. If preference has read-only flag, scripts cannot change its value nor delete it.  
+
{{Icode|readonly}} is an optional argument, thus can be omitted. If preference has read-only flag, scripts cannot change its value nor delete it.  
  
 
=== Accessing preferences ===
 
=== Accessing preferences ===
  
Once preferences are declared you can use <tt>setItem()</tt> and <tt>getItem()</tt> or bracket access to modify stored values. Please note that in current Web tools (v 1.5), only bracket access is supported in local simulator preview. There is a size limit for stored preference. Stored string should not be longer than 256 characters, same applies for the key.   
+
Once preferences are declared you can use {{Icode|setItem()}} and {{Icode|getItem()}} or bracket access to modify stored values. Please note that in current Web tools (v 1.5), only bracket access is supported in local simulator preview. There is a size limit for stored preference. Stored string should not be longer than '''256 characters''', same applies for the key.   
  
 
<code javascript>
 
<code javascript>
Line 56: Line 57:
 
</code>
 
</code>
  
If you don’t need to use local simulator preview, setItem() and getItem() can be used to access stored preferences, as defined in Storage interface [http://www.w3.org/TR/webstorage/#storage-0]. Please note that <tt>NO_MODIFICATION_ALLOWED_ERR</tt> exception is not thrown in series 40 Web Apps, when trying to modify <tt>readonly</tt> preference.  
+
If you don’t need to use local simulator preview, {{Icode|setItem()}} and {{Icode|getItem()}} can be used to access stored preferences, as defined in Storage interface [http://www.w3.org/TR/webstorage/#storage-0]. Please note that {{Icode|NO_MODIFICATION_ALLOWED_ERR}} exception is not thrown in series 40 Web Apps, when trying to modify {{Icode|readonly}} preference.  
  
 
<code javascript>
 
<code javascript>
Line 64: Line 65:
 
//get value, returns “null” if there is no match for the key
 
//get value, returns “null” if there is no match for the key
 
widget.preferences.getItem("key");
 
widget.preferences.getItem("key");
 
 
</code>
 
</code>
  
 
=== Advanced usage ===
 
=== Advanced usage ===
Among setItem and getItem, Storage interface offers following methods and attributes.  
+
Among setItem and getItem, Storage interface offers following methods and attributes.  
* <tt>length</tt>  
+
* {{Icode|length}}  
 
** Total number of key/value pairs  
 
** Total number of key/value pairs  
* <tt>key(n)</tt>  
+
* {{Icode|key(n)}}  
 
** Returns name of the n:th key in the list
 
** Returns name of the n:th key in the list
* <tt>removeItem("key")</tt>
+
* {{Icode|removeItem("key")}}
 
**Removes key/value pair.  
 
**Removes key/value pair.  
* <tt>clear()</tt>
+
* {{Icode|clear()}}
 
**Removes all stored key/value pairs.  
 
**Removes all stored key/value pairs.  
Note that in Series 40 Web Apps, <tt>removeItem(key)</tt> and  <tt>clear()</tt> removes preferences event they would be defined as readonly.  
+
Note that in Nokia Asha Web Apps, {{Icode|removeItem(key)}} and  {{Icode|clear()}} removes preferences event they would be defined as readonly.  
  
 
<code javascript>
 
<code javascript>
Line 97: Line 97:
 
== Troubleshooting ==
 
== Troubleshooting ==
 
* Web App preferences are not stored correctly after deployment to device
 
* Web App preferences are not stored correctly after deployment to device
** In some cases short URL deployment causes problems in Series 40 Web Apps version 1.5. Please use Bluetooth deployment when possible.  
+
** In some cases short URL deployment causes problems in Nokia Asha Web Apps version 1.5. Please use Bluetooth deployment when possible.  
  
 
* Preferences are lost after reloading the web app
 
* Preferences are lost after reloading the web app
** Make sure that you have declared preference in th <tt>config.xml</tt>
+
** Make sure that you have declared preference in th {{Icode|config.xml}}
 
** Make sure that key and value are under 256 character limit.
 
** Make sure that key and value are under 256 character limit.
  
*Preferences does not work in local simulator preview Series 40 Web Apps version 1.5
+
*Preferences does not work in local simulator preview Nokia Asha Web Apps version 1.5
** Use bracket access <tt>widget.preferences["key"]</tt> instead of <tt>getItem() </tt>/<tt>setItem()</tt> syntax.
+
** Use bracket access {{Icode|widget.preferences["key"]}} instead of {{Icode|getItem() }}/{{Icode|setItem()}} syntax.

Latest revision as of 06:38, 23 May 2013

This article explains how to store data using widget.preferences in Nokia Asha Web Apps

Article Metadata
Tested with
Devices(s): Nokia X3-02
Compatibility
Platform(s): Nokia Asha Web Apps version 1.5
Series 40
Device(s): All Nokia Asha devices supporting Web Apps
Article
Keywords: widget.preferences
Created: isalento (12 Mar 2012)
Last edited: hamishwillee (23 May 2013)

Contents

[edit] Introduction

Widget preference allows developer to store data in key-value pairs. Series 40 Web App environment preserves stored data, and makes it available when Web App is started. Data stored into widget storage area is unique for Web App instance, i.e. preferences cannot be used to share data between two Web Apps.


[edit] How to use

[edit] Declaring preference

Preference key must always be declared in config.xml file, in Nokia Asha Web Apps, prior to use. Failing to do so does not cause immediate error, but values stored are not preserved and lost when Web App is re-started.

Declaring preference in config.xml:

<preference name="apikey" 
value="f1934gdf4tg334"
readonly="true"/>

readonly is an optional argument, thus can be omitted. If preference has read-only flag, scripts cannot change its value nor delete it.

[edit] Accessing preferences

Once preferences are declared you can use setItem() and getItem() or bracket access to modify stored values. Please note that in current Web tools (v 1.5), only bracket access is supported in local simulator preview. There is a size limit for stored preference. Stored string should not be longer than 256 characters, same applies for the key.

//set value 
widget.preferences["key"] ="value";
 
//get value, returns “undefined” if there is no match for the key
var value = widget.preferences["key"];

If you don’t need to use local simulator preview, setItem() and getItem() can be used to access stored preferences, as defined in Storage interface [1]. Please note that NO_MODIFICATION_ALLOWED_ERR exception is not thrown in series 40 Web Apps, when trying to modify readonly preference.

//set value
widget.preferences.setItem("key","value");
 
//get value, returns “null” if there is no match for the key
widget.preferences.getItem("key");

[edit] Advanced usage

Among setItem and getItem, Storage interface offers following methods and attributes.

  • length
    • Total number of key/value pairs
  • key(n)
    • Returns name of the n:th key in the list
  • removeItem("key")
    • Removes key/value pair.
  • clear()
    • Removes all stored key/value pairs.

Note that in Nokia Asha Web Apps, removeItem(key) and clear() removes preferences event they would be defined as readonly.

//total number of stored items
var count = widget.preferences.length;
 
//key string for first item in the list.
//Note that order can change when new key/value pairs are added
var keyString = widget.preferences.key(0);
 
//Removes item, with “key” from preferences
widget.preferences.removeItem("key");
 
//Clears ALL stored preferences.
widget.preferences.clear();


[edit] Troubleshooting

  • Web App preferences are not stored correctly after deployment to device
    • In some cases short URL deployment causes problems in Nokia Asha Web Apps version 1.5. Please use Bluetooth deployment when possible.
  • Preferences are lost after reloading the web app
    • Make sure that you have declared preference in th config.xml
    • Make sure that key and value are under 256 character limit.
  • Preferences does not work in local simulator preview Nokia Asha Web Apps version 1.5
    • Use bracket access widget.preferences["key"] instead of getItem() /setItem() syntax.
This page was last modified on 23 May 2013, at 06:38.
163 page views in the last 30 days.
×