Custom Name TypeAhead using IBM Connections


Source: IBM Digital Experience Wiki

Introduction

Connections has an inbuilt support for name typeahead, which is very limited and available within connections for some specific inbuilt controls. If you want to use the name typeahead within your custom code or in your other application then here is the way..


Name typeahead screens









Prerequisite

Below are the prerequisite.
  • IBM Connections
  • JQuery Library with autocomplete plugin(click hereexternal link for more information on jquery autocomplete)
This example is certified with jquery v1.9.1 and IBM Connections v4.0.

Accessing the service

As of IBM connections v4.0 and v4.5, the name typeahead service is located at below location.
/profiles/html/nameTypeahead.do
the above service takes name as parameter and returns an array of json objects as text format, shown below.


/*{
    "identifier": "member",
    "label": "name",
    "items": [{
        "name": "Member's Name",
        "userid": "userid",
        "uid": "uid",
        "member": "",
        "type": "type",
        "ext": {
            ext attributes key-value pair
        }
    }]
}*/
 
If you want to use this name typeahead control outside of ibm connections then you may need to use AjaxProxy or alter url rewrite rules accordingly.

Changing the javascript

  • Copy below code to a js file called nameTypeAhead.js
 /**

 This function applies name typeahead to the input html control.

 params:

 inputControlSelector : A selector that jquery understands. e.g. "#id_of_the_element"

 urlPrefix : Prefix to the service url, including server name and port,

             if the function is called from connections itself then this can be passed as blank string i.e. ''

             if the function is called from outside of the connections context then you may need to use ajax-proxy

 maxRowsToFetch : Maximum number of rows to be fetched from connections server. Default value is 20.

 selectCallbackFunction : A callback function, that is to be called when you perform the select.

 dataFormatFunction [optional] : A callback function to format the data, recieved from server.

 */

 function applyNameTypeAhead(inputControlSelector, urlPrefix, maxRowsToFetch, selectCallbackFunction, dataFormatFunction){

     var cache = {};

     maxRowsToFetch = maxRowsToFetch || 20;

     $(inputControlSelector).autocomplete({

                 minLength: 2,

                 source: function( request, response ) {

                     var term = request.term;

                     if ( term in cache ) {

                         response( cache[ term ] );

                         return;

                     }

                     if(urlPrefix == null)

                         urlPrefix = '';

                     

                     $.ajax({

                         url: urlPrefix + '/profiles/html/nameTypeahead.do',

                         data: {

                             count: maxRowsToFetch,

                             lang: 'en_us',

                             extended: true,

                             name: term

                         },

                         dataType: 'text',

                         success: function( data, status, xhr ) {

                             data = data.trim();

                             if (data.startsWith('/*')){

                                 data = data.substr(2);

                             }

                             if (data.endsWith('*/')){

                                 data = data.substr(0,data.length-2);

                             }

                             

                             data = $.parseJSON(data);

                             var formatFunction = null;

                             

                             if (typeof dataFormatFunction === 'function') {

                                 formatFunction = dataFormatFunction;

                             }else{

                                 formatFunction =  function(item){

                                 return {

                                     label: item.name + (item.ext.email != '' ? " - (" + item.ext.email + ")":""),

                                     value: item.name,

                                     uid: item.uid,

                                     email: item.ext.email

                                 };

                             };

                             }

                             

                             var localList = $.map(data.items, function(item){

                                 return formatFunction(item);

                             });

                             

                             cache[ term ] = localList;

                             response(localList);

                         }

                     });

                 },

                 select: function( event, ui ) {

                     event.preventDefault();

                     if (typeof selectCallbackFunction === 'function') { selectCallbackFunction(event, ui); }

                   }

             

     });

 }

 

 function applyNameTypeAhead(inputControlSelector, urlPrefix, maxRowsToFetch, selectCallbackFunction){

     applyNameTypeAhead(inputControlSelector, urlPrefix, maxRowsToFetch, selectCallbackFunction, '');

 }

  
 
  • Include the nameTypeAhead.js or copy + paste the applyNameTypeAhead function in any of the existing js file.
   e.g. <script src="/applyNameTypeAhead.js">script
 

  • Note down the selector for the input element on which you want to apply name typeahead.
        e.g. if the input looks like
 <input type="text" name="testNameTypeAheadName" id="testNameTypeAheadId"> 
        then selector could be "#testNameTypeAheadId" or may be '[name="manageProfileProxyField-displayName"]'
  • To apply the name typeahead, you must call applyNameTypeAhead() with below parameters.
inputControlSelector : A selector that jquery understands. e.g. "#id_of_the_element"
urlPrefix : Prefix to the service url, including server name and port,
            if the function is called from connections itself then this can be passed as blank string i.e. ''
            if the function is called from outside of the connections context then you may need to use ajax-proxy url prefix.
maxRowsToFetch : Maximum number of rows to be fetched from connections server. Default value is 20.
selectCallbackFunction : A callback function, that is to be called when you perform the select.
dataFormatFunction [optional] : A callback function to format the data, received from server.

Example code

Here is an example:
Assumptions
  • jquery and autocomplete plugin are included in the page.
  • There is an input element on the page.
     <input type="text" name="testNameTypeAheadName" id="testNameTypeAheadId">
  • Call is from connections server itself
 var formatFunction =  function(item){

                                 return {

                                     label: item.name + (item.ext.email != '' ? " - (" + item.ext.email + ")":""),

                                     value: item.name,

                                     uid: item.uid,

                                     email: item.ext.email

                                 };

                             };
  
 var selectFunction = function(event, ui){

     console.log('select function called..');

     console.log(event);

     console.log(ui);

     $('#testNameTypeAhead').val(ui.item.email);

 };
 applyNameTypeAhead('#testNameTypeAheadId', '', 20, selectFunction, formatFunction);
 

Now your input control should be able to provide you suggestions as you type names.

About author


Navin Manwatkar a Product Consultant (IBM Connections and WebSphere Portal) working with Lab services division of India Software Labs. His skills and interests include WebSphere Portal, WebSphere Application Server, IBM Connections, Java / JavaEE development and Web Designing. You can reach him at navinmanwatkar@in.ibm.com

Comments

Popular posts from this blog

Transferring an IBM xPages application to another server

Shutdown/Restart Lotus Domino Server via Program Document