Mobile Web

Task: Call Log

This task, based on the CallLog sample delivered with the Tizen SDK, demonstrates how you can use the Call History API to manage call logs in your application. For more information on the sample functionality and creating the sample with the full source code, see CallLog.

This task consists of the following parts:

This sample is a fully functional application for displaying a detailed call history of the device or of a specific caller. The user can respond by calling or sending a message. Additionally, the user can delete a call history log.

Defining the Application Layout

The CallLog sample application layout uses the template manager based on the MVC (Model-View-Controller) architecture, and consists of 2 screens: the main screen displays the entire call history and the History for Caller screen displays the detailed call history of a specific caller.

The following figure shows the main screens of the application.

Figure: CallLog screens

CallLog screens

Using the Template Manager

The template manager enables the HTML output generation to be divided into 3 parts.

  1. app.ui.templateManager.js Source File
    1. The template manager loads the template files into the cache.

      loadToCache: function TemplateManager_loadToCache(tplNames, onSuccess)
      {
         var self = this,
         cachedTemplates = 0,
         tplName,
         tplPath;
      
         if ($.isArray(tplNames))
         {
            $.each(tplNames, function(index, fileName)
            {
               if (self.cache[fileName] === undefined)
               {
                  tplName = [fileName, app.config.get('templateExtension')].join('');
                  tplPath = [app.config.get('templateDir'), tplName].join('/');
                  $.ajax(
                  {
                     url: tplPath,
                     cache: true,
                     dataType: 'html',
                     async: true,
                     success: function(data)
                     {
                        cachedTemplates += 1;
                        self.cache[fileName] = data;
                        if (cachedTemplates >= tplNames.length && typeof onSuccess === 'function')
                        {
                           onSuccess();
                        }
                     },
                     error: function(jqXHR, textStatus, errorThrown)
                     {
                        console.error('templateManagerError: ' + errorThrown);
                     }
                  });
               }
               else
               {
                  cachedTemplates += 1;
                  if (cachedTemplates >= tplNames.length && typeof onSuccess === 'function')
                  {
                     onSuccess();
                  }
               }
            });
         }
      }
    2. Next, the template manager returns the template HTML content from the cache.

      get: function TemplateManager_get(tplName, tplParams)
      {
         if (this.cache[tplName] !== undefined)
         {
            return this.getCompleted(this.cache[tplName], tplParams);
         }
      
         return '';
      }
    3. Finally, the template manager returns the completed template using the specified parameters.

      getCompleted: function TemplateManager_getCompleted(tplHtml, tplParams)
      {
         var tplParam, replaceRegExp;
      
         for (tplParam in tplParams)
         {
            if (tplParams.hasOwnProperty(tplParam))
            {
               replaceRegExp = new RegExp(['%', tplParam, '%'].join(''), 'g');
               tplHtml = tplHtml.replace(replaceRegExp, tplParams[tplParam]);
            }
         }
      
         return tplHtml;
      }

Defining the Main Screen

  1. callView.tpl Source File
    1. The main screen of the application displays an aggregated call history list sorted by date. The header section of the screen is defined within a <div> element whose data-role attribute is set to header. The header section determines the title of the screen.

      <div data-role="page" id="callView">
         <!--Header section-->
         <div data-role="header" id="page-header" data-position="fixed">
            <h1>CALL LOG</h1>
         </div>
    2. The actual content section of the screen is defined within a <div> element whose data-role attribute is set to content. The content section of the main screen contains a list component (in mobile or wearable applications) displaying the elements listed in the templates/callItemRow.tpl and templates/dateRow.tpl files. To display the search bar, the data-filter attribute is set to true.

         <!--Content section-->
         <div id="page-content-scroll">
            <div id="page-content">
               <ul data-role="listview" id="calllogList" data-filter="true" 
                   data-position="fixed" data-insert="true"></ul>
            </div>
         </div>
      </div>
  2. dateRow.tpl Source File

    The dateRow.tpl template file defines the date at which a call has been logged in the history.

    <li class="date">%date%</li>
  3. callItemRow.tpl Source File

    The callItemRow.tpl template file defines the details of each call.

    <li data-filtertext="%name%" class="%cssClasses%">
       <div class="toRemove hidden"><input type="checkbox" /></div>
       <div class="numberOrName">%name%</div>
       <div class="iconStatus"></div>
       <div class="callTime">%callTime%</div>
    </li>

Initializing the Application

  1. config.xml Source File

    The required privileges are declared in the config.xml file.

    <!--Configuration file content-->
    <widget ...>
       <!--Other configuration details-->
       <tizen:privilege name="http://tizen.org/privilege/application.launch"/>
       <tizen:privilege name="http://tizen.org/privilege/callhistory.read"/> 
       <tizen:privilege name="http://tizen.org/privilege/callhistory.write"/> 
       <tizen:privilege name="http://tizen.org/privilege/contact.read"/> 
    </widget>

Browsing a Call Log

This section builds upon the elements described in Searching for Call History Items.

The call log retrieval functionality is implemented in the app.model.js file.

  1. Retrieving the Complete Call History
    1. The find() method of the CallHistory interface, placed in the app.model.js file, is used to retrieve the call history in the descending order by specifying the required parameters.

      getCallHistory: function Model_getCallHistory(onSuccess, onError)
      {
         tizen.callhistory.find(onSuccess, onError, null, new tizen.SortMode('startTime', 'DESC'));
      }
    2. The showCallHistory() method, placed in the app.js file, calls the getCallHistory() method from app.model.js and shows the results of the call history retrieval on the screen.

      showCallHistory: function App_showCallHistory() 
      {
         this.model.getCallHistory(this.ui.showCallHistory.bind(this.ui));
      }
  2. Retrieving the Call History for a Specific Caller
    1. To retrieve the call history for a specific caller, the phone number of the caller is specified as an additional filter parameter in the find() method.

      getCallHistoryForCaller: function Model_getCallHistoryForCaller(phoneNumber, onSuccess)
      {
         tizen.callhistory.find(onSuccess, null,
                                new tizen.AttributeFilter('remoteParties.remoteParty',
                                                          'EXACTLY', phoneNumber),
                                new tizen.SortMode('startTime', 'DESC'));
      }
      
    2. The showHistoryForCaller() method calls the getCallHistoryForCaller() method and shows the results of the specific caller history retrieval on the screen.

      showHistoryForCaller: function App_showHistoryForCaller(phoneNumber) 
      {
         this.lastViewedCaller = phoneNumber;
         this.model.getCallHistoryForCaller(phoneNumber, 
                                            this.ui.showHistoryForCaller.bind(this.ui, phoneNumber));
      }

Managing Caller History

This section builds upon the elements described in Removing Call History Items.

Listening to Call History Changes

  1. app.model.js Source File

    The addChangeListener() method of the CallHistory interface is used to add an event listener for listening to change events in the call history.

    registerChangeListener: function Model_registerChangeListener(onSuccessCallback)
    {
       var callHistoryListener =
       {
          onadded: onSuccessCallback,
          onchanged: onSuccessCallback,
          onremoved: onSuccessCallback
       };
    
       tizen.callhistory.addChangeListener(callHistoryListener);
    }
  2. app.js Source File

    The registerChangeListener() method is called during the application initialization to register the defined event handlers.

    init: function App_init() 
    {
       this.config = new Config();
       this.model = new Model();
       this.model.registerChangeListener(this.updateCallLists.bind(this));
    
       this.ui = new Ui();
    
       return this;
    }

Deleting the Call History for a Caller

  1. app.model.js Source File

    The remove() method of the CallHistory interface is used to delete a specific call log entry.

    deleteLog: function Model_deleteLog(entry)
    {
       try
       {
          tizen.callhistory.remove(entry);
       }
    }

Responding to a Call Log Entry

The call log entry response functionality is implemented in the app.js file.

  1. Calling

    The ApplicationControl interface of the Application API is used to launch other applications. To respond to the call log by calling, specify the http://tizen.org/appcontrol/operation/dial operation and the contact number as parameters.

    makeCall: function App_makeCall(phoneNumber)
    {
       var self = this, appControl = new tizen.ApplicationControl('http://tizen.org/appcontrol/operation/call',
                                                                  'tel:' + phoneNumber);
    
       tizen.application.launchAppControl(appControl, null, function() {}, function(e) 
       {
          /* Error handling */
       },
       {
          onsuccess: function() {},
          onfailure: function(er)
          {
             /* Error handling */
          }
       }
    },
  2. Sending a Message

    To respond to the call log by sending a message, specify the http://tizen.org/appcontrol/operation/compose operation and the contact number as parameters.

    sendSms: function App_sendSms(phoneNumber)
    {
       var self = this, appControl = new tizen.ApplicationControl('http://tizen.org/appcontrol/operation/compose',
                                                                  'sms:' + phoneNumber);
    
       tizen.application.launchAppControl(appControl, null, function() {}, function(e)
       {
          /* Error handling */
       },
       {
          onsuccess: function() {},
          onfailure: function(er)
          {
             /* Error handling */
          }
       });
    }