Configuring Context-Sensitive Custom Tabs

Microsoft Office Communications Server 2007 and Microsoft Office Communications Server 2007 R2 will reach end of support on January 9, 2018. To stay supported, you will need to upgrade. For more information, see Resources to help you upgrade your Office 2007 servers and clients.

You can extend the Office Communicator 2007 user interface by adding pages of Web-based content to the Office Communicator window. The pages appear in a pane just below the Contact List, and the user switches between pages by clicking tabs at the bottom of the pane.

Anything that works on a Web page, including interactive content, will work in a custom tab window—for example, Active Server Pages, Microsoft SharePoint® Services Web parts, Microsoft ActiveX® controls, or scripted applications.

Custom tabs are particularly powerful because they enable Office Communicator to pass the URIs of the current user and any selected contacts to the current page.

Setting up a custom tab requires:

  • A network-accessible custom tab definition file in XML format that gives the location of each tab's main page and controls the information Communicator passes to this page.

  • A registry entry in the \Software\Policies\Microsoft\Communicator registry hive that gives the location of the tab definition file.

  • A graphic in Portable Network Graphics (PNG) format for the tab. The graphic can be either:

    • Up to 16 pixels high by 16 pixels wide.

    • Exactly 32 pixels high by 32 pixels wide.

  • One or more Web pages for display in the Office Communicator window.

Defining the Registry Setting

A registry string value, TabURL, contains a URL that points to the XML descriptor file. TabURL can be added to the following registry keys.

HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Communicator

HKEY_CURRENT_USER\Software\Policies\Microsoft\Communicator

The TabURL setting can be added to either section of the registry. However, settings in the HKEY_LOCAL_MACHINE\SOFTWARE section take precedence.

Creating the Custom Tab Definition File

Office Communicator 2007 uses an XML tab definition file to define the displayed tabs and the address of the each tab's main page.

The tab definition file has the following format:

XML Tab Definition File Format

<?xml version="1.0" ?>
<tabdata>
  <tab>
    <image>http://site/image.png</image>
    <name>Tab title</name>
    <tooltip>Tooltip text</tooltip>
    <contenturl> http://site/content</contenturl>
    <userid>true</userid>
    <contactid>true</contactid>
    <accessibility>inside</accessibility>
  </tab>
</tabdata>

Table 6 describes each of the XML elements in the file.

Table 6.   XML elements in the Custom Tab Definition file

XML Element Description Required Element

!ELEMENT tabdata tab*

Contains zero or more tab elements. The maximum number of tab elements is 32.

No

!ELEMENT tab (image, name, tooltip, contenturl, userid, contactid, accessibility)

Contains image, name, tooltip, contenturl, userid, contactid, and accessibility elements.

No

!ELEMENT image %URI

Provides a URL for the tab image icon. The image must be in PNG format.

No

!ELEMENT name (#PCDATA)

A friendly name for the XML node. This is not displayed in the user interface.

Yes

!ELEMENT tooltip (#PCDATA)

Displays the text of the tooltip when the mouse pauses over the tab.

No

!ELEMENT contenturl %URI

Provides the URI of the page to be displayed when the user selects the tab. The file must be located on the intranet, or on a secure or trusted site on the Internet. The link must be in https:// format (recommended), or in http:// or file:/// format.

Yes

!ELEMENT userid ("true" | "false")

Determines whether Communicator will pass the user’s Session Initiation Protocol (SIP) account ID information to the tab URL. The default value is "false."

No

!ELEMENT contactid ("true" | "false")

Determines whether Communicator will pass the SIP account ID of selected contacts or distribution groups, or the name of selected user-defined groups, to the custom tab. The default value is "false."

No

!ELEMENT accessibility ("inside" | "outside" | "both")

Determines whether the URL must be displayed when the user logs in from inside the enterprise, outside the enterprise, or both. This is provided so that Communicator 2007 does not attempt to display intranet pages when the user logs in from outside the company, resulting in a "page not found" error.

No

Note

The tab icon must be in Portable Network Graphics (PNG) format. If the PNG file cannot be found or is not in the correct format, Communicator displays a default icon.

The HTML file containing the tab content must be in a trusted location on the network. The XML and PNG files can be stored in the same location as the HTML file, or on a network server or local machine. For example:

  • file:///\\contonso-it\oc\tabs.xml

  • file:///c:/myTab/tabs.xml

The following example shows a tab definition file with two tabs.

Tab definition file example

<?xml version="1.0"?> 
<tabdata>
  <tab> 
    <image>http://contoso/wm5/myservice/news.png</image> 
    <name>News</name> 
    <tooltip>Technology News</tooltip> 
    <contenturl>https://www.contoso.com/news</contenturl> 
    <userid>true</userid>
    <contactid>true</contactid>
  </tab> 
  <tab> 
    <image>http://contoso/wm5/myservice/sports.png</image> 
    <name>Sports</name> 
    <tooltip>Sports News</tooltip> 
    <contenturl>https://www.contoso.com/sports</contenturl> 
    <userid>true</userid>
    <contactid>true</contactid>
  </tab> 
</tabdata>

Note

The XML file can be used to configure up to 32 tabs on the client. However, exercise some caution, because a long list of tabs on a client computer that uses a low-resolution screen can become difficult for the user to manage.

Displaying Contextual Content in Custom Tabs

You can develop custom tab content that is specific to the current user or the currently selected contact names. When you set <contactid> or <userid> to true, Communicator sends the following two types of contextual information to your Web page:

  • The SIP URI of the current user, appended to the URL of the custom tab page.

  • An OnSelectionChange function call, sent automatically by Communicator every time one or more contacts are selected, or the current selection changes.

If the <userid> is, for example, sip:mallen@contoso.com, the URL used to retrieve the custom tab content is http://moc.corp.contoso.com/corpnews.html?userid= sip:mallen@contoso.com.

To retrieve the names of the currently selected contacts, use a scripting language to add an OnSelectionChange function to the Web page. OnSelectionChange has the following syntax:

OnSelectionChange(contacts, groups, distribution_groups)

The contacts and distribution_groups parameters contain SIP URIs of contacts and distribution groups, and the groups parameter contains the name of the group. If more than one contact or distribution group is selected, the SIP URIs are separated by semi-colons. Parameters that are not applicable at the time the OnSelectionChange event occurs are assigned a NULL value.

The following example shows how OnSelectionChange might be used on a simple Web page:

<html>
<head>
<title>Context-Sensitive Custom Tab</title>
<script language="javascript" >

function OnSelectionChange (ocContacts, ocGroups, ocDgs)
{
   document.SelectionTest.contacts.value = ocContacts;
   document.SelectionTest.groups.value = ocGroups;
   document.SelectionTest.dgs.value = ocDgs;
}

function getUserName()
{
   var params = location.search; //returns any form data appended to the URL
   // regular expression returns the user ID in the second backreference
   var parseParams = new RegExp("(userid=)([-a-zA-Z0-9+@._:]*)");
   var name = "";
   if  (params == "") 
      name = "There is no data appended to the URL" ;
   else 
   {
      parseParams.exec(params);
      name = RegExp.$2;
   };
   document.SelectionTest.userid.value = name;
}
</script>
</head>
<body> 
<center>
<form name="SelectionTest" method="post">
  <b>Context-Sensitive Custom Tab</b>
  <table>
    <tr>
      <td style="width: 100px"> User ID</td>
      <td style="width: 100px">
        <input type="text" name="userid" size=100></font>
      </td>
    </tr>
    <tr>
      <td colspan="2">
        <b>Select one or more contacts, groups, or distribution groups:</b>
      </td>
    </tr>
    <tr>
      <td style="width: 100px"> Contacts</td>
      <td style="width: 100px">
        <input type="text" name="contacts" size=100>
      </td>
    </tr>
    <tr>
      <td style="width: 100px"> Groups</td>
      <td style="width: 100px">
        <input type="text" name="groups" size=100>
      </td>
    </tr>
    <tr>
      <td style="width: 100px; height: 23px"> Distribution Groups</td>
      <td style="width: 100px; height: 23px">
        <input type="text" name="dgs" size=100>
      </td>
    </tr>
  </table>
    
<script language="javascript" >
  getUserName();
</script>

</form>
</body>
</html>