×
Namespaces

Variants
Actions
(Difference between revisions)

Adding contacts to a group in Symbian Web Runtime

From Nokia Developer Wiki
Jump to: navigation, search
seppo_fn (Talk | contribs)
m
hamishwillee (Talk | contribs)
m (Hamishwillee - Add Abstract. Tidy wiki text)
 
(18 intermediate revisions by 5 users not shown)
Line 1: Line 1:
__NOTOC__
+
[[Category:Symbian Web Runtime]][[Category:Code Examples]][[Category:PIM]][[Category:S60 5th Edition]]
__NOEDITSECTION__
+
{{Abstract|This code snippet shows how to add an existing contact to a contact group using the Contacts Platform Service for Web Runtime.}} It is supported from S60 5th Edition onwards.
{{CodeSnippet
+
 
|id= 
+
{{ArticleMetaData <!-- v1.2 -->
|platform=S60 5th Edition
+
|sourcecode= [[Media:AddingContactsToGroup.zip]] [[Media:AddingContactsToGroup.diff.zip]]
|devices=Nokia 5800 XpressMusic, Nokia N97
+
|installfile= <!-- Link to installation file (e.g. [[Media:The Installation File.sis]]) -->
|category=Web Runtime (WRT)
+
|devices= Nokia 5800 XpressMusic
|subcategory=Phonebook / Contacts
+
|sdk= <!-- SDK(s) built and tested against (e.g. [http://linktosdkdownload/ Nokia Qt SDK 1.1]) -->
|creationdate=January 28, 2009
+
|platform= S60 5th Edition and later
|keywords=device.getServiceObject(), Service.IDataSource.GetList(), Service.IDataSource.Organise()
+
|devicecompatability= <!-- Compatible devices (e.g.: All* (must have GPS) ) -->
 +
|dependencies= <!-- Any other/external dependencies e.g.: Google Maps Api v1.0 -->
 +
|signing= <!-- Empty or one of Self-Signed, DevCert, Manufacturer -->
 +
|capabilities= <!-- Capabilities required by the article/code example (e.g. Location, NetworkServices. -->
 +
|keywords= device.getServiceObject(), Service.IDataSource.GetList(), Service.IDataSource.Organise()
 +
|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= 20090226
 +
|author= [[User:Ivruban]]
 +
<!-- The following are not in current metadata -->
 +
|id= CS001397
 
}}
 
}}
 
  
 
==Overview==
 
==Overview==
  
This code snippet shows how to add an existing contact to a contact group using Contacts Platform Service for Web Runtime, supported from S60 5th Edition onwards.
+
To obtain access to the service object for the Contacts Service API, the method {{Icode|getServiceObject("Service.Contact", "IDataSource")}} is used.
  
To obtain access to service object for the Contacts Service API, method
+
In the application startup, the list of contacts and contact groups is loaded using the function {{Icode|Service.IDataSource.GetList()}}. The {{Icode|criteria}} object is used to determine the type of data.
<tt>getServiceObject("Service.Contact", "IDataSource")</tt> is used.
+
  
While initialization application load list of contacts and contacts groups
+
After choosing the contact and contact group, the function {{Icode|Service.IDataSource.Organise()}} is used to add the contact to the contact group. To set up correct values for the function {{Icode|Service.IDataSource.Organise()}}, the {{Icode|criteria}} object is used.
using function <tt>Service.IDataSource.GetList()</tt>. <tt>criteria</tt> object
+
used to determine the type of data.
+
After choosing the contact and contact group <tt>Service.IDataSource.Organise()</tt> function used to add the contact
+
to contact group. To setup a correct values for <tt>Service.IDataSource.Organise()</tt> function <tt>criteria</tt> object used.<br>
+
  
Object <tt>criteria</tt> contains a <tt>Type</tt>, <tt>Data</tt> and <tt>OperationType</tt> to define the organize operation.<br>
+
The {{Icode|criteria}} object contains {{Icode|Type}}, {{Icode|Data}}, and {{Icode|OperationType}} to define the organising operation.
  
Object <tt>groupdata</tt> used to define the contact group and contacts for <tt>criteria.Data</tt> object.
+
The {{Icode|groupdata}} object is used to define the contact group and contacts for the {{Icode|criteria.Data}} object.
  
 
==Source file: Relevant HTML components==
 
==Source file: Relevant HTML components==
  
 
<code xml>
 
<code xml>
<select id = "contacts" size = "5">
+
<select id="contacts" size="5">
 
     <option></option>
 
     <option></option>
 
</select><br/>
 
</select><br/>
<select id = "groups" size = "5">
+
<select id="groups" size="5">
 
     <option></option>
 
     <option></option>
 
</select><br/>
 
</select><br/>
<input type = "button" onclick = "doAdd();"
+
<input type="button" onclick="doAdd();" value="Add to group" />
    value = "Add to group"/>
+
 
</code>
 
</code>
  
 
==Source file: JavaScript file==
 
==Source file: JavaScript file==
<code javascript>
 
window.onload = init;
 
  
 +
<code javascript>
 
// Declare the service object
 
// Declare the service object
var so;
+
var so = null;
/**
+
</code>
* Java Script function
+
 
* Fill the list of contacts
+
<code javascript>
* @param iterator List of contacts, equals result.ReturnValue of
+
// Initializes the widget
* Service.IDataSource.GetList() function return value
+
function init() {
*/
+
     try {
function fillContactsList(iterator){
+
         //Get the service object
    var contactList = document.getElementById("contacts");
+
         so = device.getServiceObject("Service.Contact", "IDataSource");
     try{
+
         iterator.reset();
+
         var item;
+
        while (( item = iterator.getNext()) != undefined ){
+
            // Last name of contact
+
            var lastName = item.LastName.Value;
+
            // First name of contact
+
            var firstName = item.FirstName.Value;
+
            // Contact id
+
            var id = item.id;
+
            var node = document.createElement("option");
+
            node.value = id;
+
            node.appendChild (document.createTextNode(lastName + " " +
+
                firstName));
+
            contactList.appendChild(node);
+
        }
+
 
     } catch (e) {
 
     } catch (e) {
         alert("fillContactsList" + e);
+
         alert("init: " + e );
 
     }
 
     }
}
+
 
/**
+
    // Clean the contact list
* Java Script function
+
    var contactList = document.getElementById("contacts");
* Fill the list of groups
+
    while (contactList.length != 0){
* @param iterator List of groups, equals result.ReturnValue of
+
        contactList.remove(0);
* Service.IDataSource.GetList() function return value
+
    }
*/
+
    // Clean the contact group list
function fillGroupsList(iterator){
+
 
     var groupList = document.getElementById("groups");
 
     var groupList = document.getElementById("groups");
     try{
+
     while (groupList.length != 0){
        iterator.reset();
+
        groupList.remove(0);
        var item;
+
        while (( item = iterator.getNext()) != undefined ){
+
            // Name of group
+
            var groupName = item.GroupLabel;
+
            // Group's id
+
            var id = item.id;
+
            var node = document.createElement ("option");
+
            node.value = id;
+
            node.appendChild (document.createTextNode(groupName));
+
            groupList.appendChild(node);
+
        }
+
    } catch (e) {
+
        alert("fillContactsList" + e);
+
 
     }
 
     }
 +
    // Get the list of contacts
 +
    getContactList();
 +
    // Get the list of contact groups
 +
    getGroupsList();
 +
    // Select the first contact group
 +
    groupList.options[0].selected = true;
 +
    // Select the first contact
 +
    contactList.options[0].selected = true;
 +
   
 +
    // ...
 
}
 
}
 +
</code>
  
 +
<code javascript>
 
/**
 
/**
* Java Script function
+
* Java Script function
* Get the list of contacts
+
* Get the list of contacts
*/
+
*/
 
function getContactList() {
 
function getContactList() {
 
     // Criteria for Service.IDataSource.GetList() function
 
     // Criteria for Service.IDataSource.GetList() function
Line 114: Line 104:
 
         var result;
 
         var result;
 
         // Service.IDataSource.GetList() function - method retrieves a list of
 
         // Service.IDataSource.GetList() function - method retrieves a list of
         //contacts
+
         // contacts
 
         result = so.IDataSource.GetList(criteria);
 
         result = so.IDataSource.GetList(criteria);
         if( result.ErrorCode == 0) {
+
         if (result.ErrorCode == 0) {
 
             //Fill the list of contacts
 
             //Fill the list of contacts
 
             fillContactsList(result.ReturnValue);
 
             fillContactsList(result.ReturnValue);
Line 126: Line 116:
 
     }
 
     }
 
}
 
}
 +
 +
/**
 +
* Java Script function
 +
* Fill the list of contacts
 +
* @param iterator List of contacts, equals result.ReturnValue of
 +
* Service.IDataSource.GetList() function return value
 +
*/
 +
function fillContactsList(iterator) {
 +
    var contactList = document.getElementById("contacts");
 +
    try{
 +
        iterator.reset();
 +
        var item;
 +
        while ((item = iterator.getNext()) != undefined) {
 +
            // Last name of contact
 +
            var lastName = "";
 +
            if (item.LastName != undefined) {
 +
                lastName = item.LastName.Value;
 +
            }
 +
            // First name of contact
 +
            var firstName = "";
 +
            if (item.FirstName != undefined) {
 +
                firstName = item.FirstName.Value;
 +
            }
 +
            // Contact id
 +
            var id = item.id;
 +
            var node = document.createElement("option");
 +
            node.value = id;
 +
            node.appendChild(document.createTextNode(lastName + " " +
 +
                firstName));
 +
            contactList.appendChild(node);
 +
        }
 +
    } catch (e) {
 +
        alert("fillContactsList" + e);
 +
    }
 +
}
 +
 
/**
 
/**
* Java Script function
+
* Java Script function
* Get the list of contacts
+
* Get the list of contact groups
*/
+
*/
 
function getGroupsList() {
 
function getGroupsList() {
 
     // Criteria for Service.IDataSource.GetList() function
 
     // Criteria for Service.IDataSource.GetList() function
Line 138: Line 164:
 
         var result;
 
         var result;
 
         // Service.IDataSource.GetList() function - method retrieves a list of
 
         // Service.IDataSource.GetList() function - method retrieves a list of
         //contact groups
+
         // contact groups
 
         result = so.IDataSource.GetList(criteria);
 
         result = so.IDataSource.GetList(criteria);
         if(result.ErrorCode == 0) {
+
         if (result.ErrorCode == 0) {
             //Fill the list of contact groups
+
             // Fill the list of contact groups
 
             fillGroupsList(result.ReturnValue);
 
             fillGroupsList(result.ReturnValue);
 
         } else {
 
         } else {
             alert("Error in getting contact list");
+
             alert("Error in getting contact list: " + result.ErrorCode);
 
         }
 
         }
 
     } catch (e) {
 
     } catch (e) {
         alert ("getContactList: " + e);
+
         alert("getContactList: " + e);
 
     }
 
     }
 
}
 
}
  
// Initializes the widget
+
/**
function init() {
+
* Java Script function
 +
* Fill the list of groups
 +
* @param iterator List of groups, equals result.ReturnValue of
 +
* Service.IDataSource.GetList() function return value
 +
*/
 +
function fillGroupsList(iterator) {
 +
    var groupList = document.getElementById("groups");
 
     try {
 
     try {
         //Get the service object
+
         iterator.reset();
        so = device.getServiceObject("Service.Contact", "IDataSource");
+
        var item;
 +
        while ((item = iterator.getNext()) != undefined) {
 +
            // Name of group
 +
            var groupName = item.GroupLabel;
 +
            // Group's id
 +
            var id = item.id;
 +
            var node = document.createElement ("option");
 +
            node.value = id;
 +
            node.appendChild(document.createTextNode(groupName));
 +
            groupList.appendChild(node);
 +
        }
 
     } catch (e) {
 
     } catch (e) {
         alert("init: " + e );
+
         alert("fillContactsList" + e);
 
     }
 
     }
    // Clean the contact list
 
    var contactList = document.getElementById("contacts");
 
    while(contactList.length != 0){
 
        contactList.remove(0);
 
    }
 
    // Clean the contact group list
 
    var groupList = document.getElementById("groups");
 
    while(groupList.length != 0){
 
        groupList.remove(0);
 
    }
 
    // Get the list of contacts
 
    getContactList();
 
    // Get the list of contact groups
 
    getGroupsList();
 
    // Select the first contact group
 
    groupList.options[0].selected = true;
 
    // Select the first contact
 
    contactList.options[0].selected = true;
 
 
}
 
}
 +
 
// Add selected contact to the selected contact group
 
// Add selected contact to the selected contact group
function doAdd(){
+
function doAdd() {
 
     var contact;
 
     var contact;
 
     var group;
 
     var group;
 
     // Get the selected contact group
 
     // Get the selected contact group
 
     var groupList = document.getElementById("groups");
 
     var groupList = document.getElementById("groups");
     for(var i = 0; i < groupList.options.length; i++) {
+
     for (var i = 0; i < groupList.options.length; i++) {
 
         if (groupList.options[i].selected) {
 
         if (groupList.options[i].selected) {
 
             group = groupList.options[i];
 
             group = groupList.options[i];
Line 191: Line 216:
 
     // Get the selected contact
 
     // Get the selected contact
 
     var contactList = document.getElementById("contacts");
 
     var contactList = document.getElementById("contacts");
     for(var i = 0; i < contactList.options.length; i++) {
+
     for (var i = 0; i < contactList.options.length; i++) {
 
         if (contactList.options[i].selected) {
 
         if (contactList.options[i].selected) {
 
             contact = contactList.options[i];
 
             contact = contactList.options[i];
Line 213: Line 238:
 
         // Organise method adds contacts to a contact group (association)
 
         // Organise method adds contacts to a contact group (association)
 
         var result = so.IDataSource.Organise(criteria);
 
         var result = so.IDataSource.Organise(criteria);
         if(result.ErrorCode == 0) {
+
         if (result.ErrorCode == 0) {
 
             alert("Contact added to group successfully");
 
             alert("Contact added to group successfully");
 
         } else {
 
         } else {
Line 223: Line 248:
 
}
 
}
 
</code>
 
</code>
 +
 
==Postconditions==
 
==Postconditions==
After starting of application, the "Contacts" and "Contact Groups" listboxes are shown.
 
<br>
 
To associate contact to the contact group use "Add to group" button.
 
  
==Supplementary material==
+
At startup, the "Contacts" and "Contact Groups" listboxes are shown.
  
* You can test the adding of contact to contact group in action in a simple, executable application into which this code snippet has been patched. The executables and source files are available for download at: [[Media:AddingContactsToGroup.zip]].
+
To associate a contact with a contact group, use the "Add to group" button.
 +
 
 +
==Supplementary material==
  
* You can examine all the changes that are required to implement the above mentioned features in an application. The changes are provided in unified diff and color-coded diff formats: [[link_to_patchs]]
+
This code snippet is part of the stub concept, which means that it has been patched on top of a template application in order to be more useful to developers. The version of the WRT stub application used as a template in this snippet is v1.1.
  
[[Category:Web Runtime (WRT)]][[Category:Code Examples]]
+
* The patched, executable application that can be used to test the features described in this snippet is available for download at [[Media:AddingContactsToGroup.zip]].
 +
* You can view all the changes that are required to implement the above-mentioned features. The changes are provided in unified diff and colour-coded diff (HTML) formats in [[Media:AddingContactsToGroup.diff.zip]].
 +
* For general information on applying the patch, see [[Using Diffs]].
 +
* For unpatched stub applications, see [[Example app stubs with logging framework]].

Latest revision as of 08:48, 4 October 2012

This code snippet shows how to add an existing contact to a contact group using the Contacts Platform Service for Web Runtime. It is supported from S60 5th Edition onwards.

Article Metadata
Code ExampleTested with
Devices(s): Nokia 5800 XpressMusic
Compatibility
Platform(s): S60 5th Edition and later
S60 5th Edition
Article
Keywords: device.getServiceObject(), Service.IDataSource.GetList(), Service.IDataSource.Organise()
Created: ivruban (26 Feb 2009)
Last edited: hamishwillee (04 Oct 2012)

Contents

[edit] Overview

To obtain access to the service object for the Contacts Service API, the method getServiceObject("Service.Contact", "IDataSource") is used.

In the application startup, the list of contacts and contact groups is loaded using the function Service.IDataSource.GetList(). The criteria object is used to determine the type of data.

After choosing the contact and contact group, the function Service.IDataSource.Organise() is used to add the contact to the contact group. To set up correct values for the function Service.IDataSource.Organise(), the criteria object is used.

The criteria object contains Type, Data, and OperationType to define the organising operation.

The groupdata object is used to define the contact group and contacts for the criteria.Data object.

[edit] Source file: Relevant HTML components

<select id="contacts" size="5">
<option></option>
</select><br/>
<select id="groups" size="5">
<option></option>
</select><br/>
<input type="button" onclick="doAdd();" value="Add to group" />

[edit] Source file: JavaScript file

// Declare the service object
var so = null;
// Initializes the widget
function init() {
try {
//Get the service object
so = device.getServiceObject("Service.Contact", "IDataSource");
} catch (e) {
alert("init: " + e );
}
 
// Clean the contact list
var contactList = document.getElementById("contacts");
while (contactList.length != 0){
contactList.remove(0);
}
// Clean the contact group list
var groupList = document.getElementById("groups");
while (groupList.length != 0){
groupList.remove(0);
}
// Get the list of contacts
getContactList();
// Get the list of contact groups
getGroupsList();
// Select the first contact group
groupList.options[0].selected = true;
// Select the first contact
contactList.options[0].selected = true;
 
// ...
}
/**
* Java Script function
* Get the list of contacts
*/

function getContactList() {
// Criteria for Service.IDataSource.GetList() function
var criteria = new Object();
// Type of list
criteria.Type = "Contact";
try {
var result;
// Service.IDataSource.GetList() function - method retrieves a list of
// contacts
result = so.IDataSource.GetList(criteria);
if (result.ErrorCode == 0) {
//Fill the list of contacts
fillContactsList(result.ReturnValue);
} else {
alert("Error in getting contact list");
}
} catch (e) {
alert ("getContactList: " + e);
}
}
 
/**
* Java Script function
* Fill the list of contacts
* @param iterator List of contacts, equals result.ReturnValue of
* Service.IDataSource.GetList() function return value
*/

function fillContactsList(iterator) {
var contactList = document.getElementById("contacts");
try{
iterator.reset();
var item;
while ((item = iterator.getNext()) != undefined) {
// Last name of contact
var lastName = "";
if (item.LastName != undefined) {
lastName = item.LastName.Value;
}
// First name of contact
var firstName = "";
if (item.FirstName != undefined) {
firstName = item.FirstName.Value;
}
// Contact id
var id = item.id;
var node = document.createElement("option");
node.value = id;
node.appendChild(document.createTextNode(lastName + " " +
firstName));
contactList.appendChild(node);
}
} catch (e) {
alert("fillContactsList" + e);
}
}
 
/**
* Java Script function
* Get the list of contact groups
*/

function getGroupsList() {
// Criteria for Service.IDataSource.GetList() function
var criteria = new Object();
// Type of list
criteria.Type = "Group";
try {
var result;
// Service.IDataSource.GetList() function - method retrieves a list of
// contact groups
result = so.IDataSource.GetList(criteria);
if (result.ErrorCode == 0) {
// Fill the list of contact groups
fillGroupsList(result.ReturnValue);
} else {
alert("Error in getting contact list: " + result.ErrorCode);
}
} catch (e) {
alert("getContactList: " + e);
}
}
 
/**
* Java Script function
* Fill the list of groups
* @param iterator List of groups, equals result.ReturnValue of
* Service.IDataSource.GetList() function return value
*/

function fillGroupsList(iterator) {
var groupList = document.getElementById("groups");
try {
iterator.reset();
var item;
while ((item = iterator.getNext()) != undefined) {
// Name of group
var groupName = item.GroupLabel;
// Group's id
var id = item.id;
var node = document.createElement ("option");
node.value = id;
node.appendChild(document.createTextNode(groupName));
groupList.appendChild(node);
}
} catch (e) {
alert("fillContactsList" + e);
}
}
 
// Add selected contact to the selected contact group
function doAdd() {
var contact;
var group;
// Get the selected contact group
var groupList = document.getElementById("groups");
for (var i = 0; i < groupList.options.length; i++) {
if (groupList.options[i].selected) {
group = groupList.options[i];
}
}
// Get the selected contact
var contactList = document.getElementById("contacts");
for (var i = 0; i < contactList.options.length; i++) {
if (contactList.options[i].selected) {
contact = contactList.options[i];
}
}
// Create the contact and contact group data to update
var groupdata = new Object();
// The id of selected contact group
groupdata.id = group.value;
groupdata.IdList = new Array();
// The id of selected contact
groupdata.IdList[0] = contact.value;
// Criteria for update contact and contact group
var criteria = new Object();
criteria.Type = "Group";
criteria.Data = groupdata;
// Add the contact to group, "Disassociate" to delete
criteria.OperationType = "Associate";
 
try {
// Organise method adds contacts to a contact group (association)
var result = so.IDataSource.Organise(criteria);
if (result.ErrorCode == 0) {
alert("Contact added to group successfully");
} else {
alert("Error occurs while organizing contacts");
}
} catch (e) {
alert("Exception occure while organizing contacts: " + e);
}
}

[edit] Postconditions

At startup, the "Contacts" and "Contact Groups" listboxes are shown.

To associate a contact with a contact group, use the "Add to group" button.

[edit] Supplementary material

This code snippet is part of the stub concept, which means that it has been patched on top of a template application in order to be more useful to developers. The version of the WRT stub application used as a template in this snippet is v1.1.

This page was last modified on 4 October 2012, at 08:48.
160 page views in the last 30 days.

Was this page helpful?

Your feedback about this content is important. Let us know what you think.

 

Thank you!

We appreciate your feedback.

×