Custom Name Picker

This tutorial will get you started writing a custom name picker extension for Verse.

Structure of the Tutorial:

  1. Add Custom Name Picker Extension
  2. Secure the Application

There is much more detailed documentation available here, but it’s not required to complete the tutorial.

This is a follow on tutorial to Your First Application for IBM Verse


Add Custom Name Picker Extension

   

Edit applications.json

1. Open src/applications.json in your text editor.

2. Append the following object into the array in applications.json, and save the file. Be sure to add a comma , at the end of the last object in applications.json before adding your own.

  {
    "id": "com.ibm.verse.custom.name.picker",
    "name": "Custom Name Picker",
    "title": "Custom Name Picker",
    "description": "Sample that shows how to add a custom name picker in mail compose view",
    "extensions": [
      {
        "type": "com.ibm.verse.ext.namePicker",
        "ext_id": "com.ibm.verse.namepicker.sample.compose",
        "name": "Custom name picker in mail compose",
        "title": "Add Contact",
        "payload": {
          "url": "${extensionPath}/custom-name-picker/index.html"
        }
      }
    ],
    "payload": {},
    "services": [
      "Verse"
    ]
  }

3. Every time you make a change to the extension code, you need to reload the extension first, then reload Verse, so that the browser and Verse will pick up your latest changes.

For instructions on how to reload the extension click here.

   

Test it out

  1. In the Verse UI, click the Compose button.
  2. In the Mail Compose view, click on the To link text.
  3. From here you can pick someone to send the mail to.
  4. When you are done you can return to the message to continue editing.

Custom Name Picker

Congratulations! You successfully registered the custom name picker extension with Verse.

   

How it works

  • This step introduces a new extension point with the type com.ibm.verse.ext.namePicker
  • A custom name picker is added to the mail compose view and can be invoked by clicking the To link
  • The specified web application is opened in an embedded iframe within the mail compose view
  • Verse sends a message to the web application containing context data which includes details of the mail the user is currently editing
  • The web application displays an appropriate user interface e.g. it may list suggested names based on the content of the mail being composed
  • The web application can send messages to Verse which will cause it to insert email addresses into the currently selected field i.e with To, Cc or Bcc

Below is the snippet of JavaScript which sends a message to Verse to insert an email address into the mail compose view:

  var userEmail = this.parentNode.querySelector(".user-email").innerText;
  var userName = this.parentNode.querySelector(".user-name").innerText;
  var emails_message = {
    verseApiType: "com.ibm.verse.add.contact",
    userEmail: userEmail,
    userName: userName
  };
  evt.source.postMessage(emails_message, evt.origin);

Secure the Application

Follow the instructions to secure the application.

Hook Before Send

This tutorial will get you started writing a hook before send extension for Verse.

Structure of the Tutorial:

  1. Add Hook Before Send Extension
  2. Secure the Application

There is much more detailed documentation available here, but it’s not required to complete the tutorial.

This is a follow on tutorial to Your First Application for IBM Verse


Add Hook Before Send Extension

   

Edit applications.json

1. Open src/applications.json in your text editor.

2. Append the following object into the array in applications.json, and save the file. Don’t forget to add a comma , at the end of the preceding application before adding your own.

  {
    "id": "com.ibm.verse.app.beforeOnSend",
    "name": "Hook Before Send",
    "title": "Hook Before Send Sample",
    "description": "Sample that shows how to check for a secret value in mail being sent",
    "extensions": [
      {
        "type": "com.ibm.verse.ext.beforeOnSend",
        "ext_id": "com.ibm.verse.ext.hookbeforesend.sample",
        "name": "Hook Before Send Extension",
        "title": "Secret Value Checker",
        "payload": {
          "url": "${extensionPath}/hook-before-send/index.html"
        }
      }
    ],
    "services": [
      "Verse"
    ]
  }

3. Every time you make a change to the extension code, you need to reload the extension first, then reload Verse, so that the browser and Verse will pick up your latest changes.

For instructions on how to reload the extension click here.

   

Test it out

  1. In the Verse UI, click the Compose button.
  2. In the Mail Compose view, enter recipient and subject.
  3. Enter the text ‘Secret12345’ in the mail body.
  4. Click the send button and you will receive a warning about sending a mail containing the ‘Secret12345’.
  5. The user can go back and edit the mail before sending or can continue to send the mail as is.

Hook Before Send

Congratulations! You successfully registered the hook before send extension with Verse.

   

How it works

  • This step introduces a new extension point with the type com.ibm.verse.ext.beforeOnSend
  • The hook before send extension is added to the mail compose and is invoked when the user clients the send button
  • The associated web application is loaded into an embedded iframe which displays in the mail compose view
  • Verse sends a context message to the extension with the details of the mail being sent
  • The extension can optionally send a message to Verse to signal that it should continue sending the mail message
  • Otherwise the extension can display some data relevant to the mail message being sent

Below is the snippet of JavaScript which sends a message to Verse to signal that the mail should be sent:

  var response_message = {
    verseApiType: 'com.ibm.verse.message.continue.send'
  };
  event.source.postMessage(response_message, event.origin);

   

2. Secure the Application

Follow the instructions to secure the application.

Live Text Widget

This tutorial will get you started creating a live text extension for Verse. This is a follow-on tutorial to Your First Application for IBM Verse

There is much more detailed documentation available here, but it’s not required for completing the tutorial.


Create Live Text Extension

   

Edit applications.json

1. Open src/applications.json in your text editor.

2. Append the following object into the array in applications.json, and save the file. Don’t forget to add a comma , at the end of the preceding application before adding your own.

  {
    "name": "Live Text Widget Sample application",
    "title": "Live Text Widget Sample",
    "description": "The sample shows how to contribute a live text extension in Verse",
    "extensions": [
      {
        "name": "Live Text Widget Sample extension",
        "ext_id": "com.ibm.verse.livetext.sample",
        "type": "com.ibm.verse.ext.liveText",
        "payload": {
          "text": "Live Text Widget Action",
          "href": "${extensionPath}/${1}/sample1.html?tel=${2}",
          "recognizer": "Path:([a-z].*), Tel:([0-9]{8}).*",
          "location": "window",
          "renderParams": {
            "width": "800",
            "height": "600"
          }
        }
      }
    ],
    "payload": {},
    "services": [
      "Verse"
    ]
  }

3. Every time you make a change to the extension code, you need to reload the extension first, then reload Verse, so that the browser and Verse will pick up your latest changes.

For instructions on how to reload the extension click here.

   

Test it out

  1. In the Verse UI, click the Compose button.
  2. In the New Mail Dialog, type in Path:live-text, Tel:82451234 CN in the mail body.
  3. Send the mail to yourself.
  4. When you receive the mail, open it.
  5. You will see that the text Path:live-text, Tel:82451234 CN is recognized and underlined.
  6. Click on the underlined text, a menu will pop up with a menu item, Live Text Widget Action.

  7. Click on the menu item, Live Text Widget Action, a new browser window will be opened with “live-text/sample1.html?tel=82451234” at the end of the URL.

The GIF animation for Live Text

Congratulations! You successfully configured a Live Text extension with Verse.

   

Multiple Actions

Sometimes you might want to create multiple actions for one live text.

To do this, create multiple Live Text extensions with a recognizer property to recognize the same live text. The multiple action items will be organized into one pop-up menu for the recognized live text.

You can follow the steps above to add the following object into the array in applications.json,
and test the multiple actions.

[
  {
    "name": "Live Text Widget Multiple Actions Sample",
    "title": "The Live Text Widget Sample with Multiple Actions",
    "description": "The sample shows how to create multiple Live Text actions for the same Live Text in Verse",
    "extensions": [
      {
        "name": "Live Text Widget Action Sample One",
        "ext_id": "com.ibm.verse.livetext.sample.one",
        "type": "com.ibm.verse.ext.liveText",
        "payload": {
          "text": "Live Text Widget Action One",
          "href": "${extensionPath}/${1}/sample1.html?tel=${2}",
          "recognizer": "Path:(live-text), Tel:([0-9]{8}).*",
          "location": "window",
          "renderParams": {
            "width": "800",
            "height": "400"
          }
        }
      },
      
      {
        "name": "Live Text Widget Action Sample Two",
        "ext_id": "com.ibm.verse.livetext.sample.two",
        "type": "com.ibm.verse.ext.liveText",
        "payload": {
          "text": "Live Text Widget Action Two",
          "href": "${extensionPath}/live-text/sample2.html?tel=${2}",
          "recognizer": "Path:(live-text), Tel:([0-9]{8}).*",
          "location": "tab"
        }
      }
    ],
    "payload": {},
    "services": [
      "Verse"
    ]
  }
]

   

How it works

  1. This step introduces a new extension point with the type com.ibm.verse.ext.liveText
  2. A live text extension is configured into Verse, the recognized live text will be underlined
  3. Click on the underlined text to display the pop-up menu
  4. Click on an item in the pop-up menu and the specified web application is opened in a new window or a new tab
  5. The web application receives parameters from the URL

Third-Party Chat Service Integration

This tutorial will get you started creating a third-party chat service extension for Verse.

There is much more detailed documentation available here, but it’s not required for completing the tutorial.


Create Chat Service Extension

   

Edit applications.json

1. Open src/applications.json in your text editor.

2. Append the following object into the array in applications.json, and save the file. The object uses Jabber and WebEx as examples. Be sure to add a comma , at the end of the last object in applications.json before adding your own.

  {
    "name": "Chat Service Integration Sample",
    "title": "Chat Service Integration Sample",
    "description": "This is a sample to integrate third-party chat service in Verse",
    "extensions": [
      {"type": "com.ibm.appreg.ext.disableSametime"},
      {"type": "com.ibm.appreg.ext.disableSTMeetings"},
      {
        "type": "com.ibm.appreg.ext.templatedLink",
        "object": "com.ibm.appreg.object.person",
        "payload": {
          "text": "Jabber Chat",
          "icon": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAeAB4AAD/2wBDAAIBAQIBAQICAgICAgICAwUDAwMDAwYEBAMFBwYHBwcGBwcICQsJCAgKCAcHCg0KCgsMDAwMBwkODw0MDgsMDAz/2wBDAQICAgMDAwYDAwYMCAcIDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAz/wAARCAAbABsDASIAAhEBAxEB/8QAHwAAAQUBAQEBAQEAAAAAAAAAAAECAwQFBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQAAAF9AQIDAAQRBRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAkM2JyggkKFhcYGRolJicoKSo0NTY3ODk6Q0RFRkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKjpKWmp6ipqrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6/8QAHwEAAwEBAQEBAQEBAQAAAAAAAAECAwQFBgcICQoL/8QAtREAAgECBAQDBAcFBAQAAQJ3AAECAxEEBSExBhJBUQdhcRMiMoEIFEKRobHBCSMzUvAVYnLRChYkNOEl8RcYGRomJygpKjU2Nzg5OkNERUZHSElKU1RVVldYWVpjZGVmZ2hpanN0dXZ3eHl6goOEhYaHiImKkpOUlZaXmJmaoqOkpaanqKmqsrO0tba3uLm6wsPExcbHyMnK0tPU1dbX2Nna4uPk5ebn6Onq8vP09fb3+Pn6/9oADAMBAAIRAxEAPwD9+z0rwD40f8FLfhZ8DtV1C11C+1zVl0WXyNVudF0mfULbSnBAKyyxjbuUkBlUsynggEV7T4/1a/0HwNrF7pVoL/U7SymmtLZs7Z5VQlFOOcFgM45x05r47+BPie5+EniTQNdj+OL+OPC8saWut6Hrd5FaGzLgRpcWqmONQqZOYAArADyxuUB/fybLYV6dSvVg5qNklFtNt+fLJLyva/Ru1j4viniCrgq9HCUJKDnducoqUYpW6c8G9/s8zXVJan1b8Ffjv4R/aI8D2/iPwXr1j4g0e5A23Fs+dpxnaynDK2CDhgDyK66vk/8AZ4j8PWf7dHiK9+G9pAnhfxHo7y+Ihbo0cY1COfckxVsFd3nOAoGCWcjo2PrAVzZ1l8MJiFCndJpStL4o36S818rqzsrnpcM5vUzHCOpWtzRk4txvySt9qN9eV3++4jdK+DviR/wTUv8A4yfHNms9P1z4e+CNOvnuIorXU4roahMAwSdYxIv2eMZJVBuOSTx2+8qKMqzvG5bOVTBT5XJWf/Dbel1p0sy8+4Yy7OYwhmEOZQbt033V1aSWz91q9le60PL/ANmD9k7wz+yt4au7PQftdxd6myPfXtzIXluim7bn6F3Pc5Y5J4x6gOKKK4cViq2Jqyr4iTlOW7e7PSy7LsNgMNHCYOHJTjsl9731bb1bererP//Z",
          "href": "xmpp://${emails}",
          "locator": "chat"
        }
      },
      {
        "type": "com.ibm.appreg.ext.templatedLink",
        "object": "com.ibm.appreg.object.person",
        "payload": {
          "text": "WebEx meeting",
          "icon": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAB4AAAAeCAYAAAA7MK6iAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAACxMAAAsTAQCanBgAAARbSURBVEhL7ZZ7TJVlHMdfmsFqXRaLOYJic7OsQOBc4NxvhIhoDmfkFunQ8IgHsYwpSGCwnEoZt5kKyYhkGkoRIKFcLPvTP1picFx0mWlbzSFnh8vBc/n2ex9eqMN7jrxtzf7xuz3nOed5f8/7eX6X53kOh/9J98H3TJLAPmpueKGo6wR3yA7unQsIyW/HImsruKwTWJ9/DB7BTqoWBLvdboRXDoCrGwRXOYSoonO4QeN/UrtJ7bG1NYhKq0a05QjiMnbyUyQpCPgOLd+LP+jbQycmwB3/DROTLsDjBn36y0vN58J3P9HL1r6AsI2JmKL5Hv6Bzz1jE0CBwXcm8SN1YZ/8gqrvnUIIvawXhVMY4Lu+65fx6KZ4RG6XYZSW6GKrCqzAYI8XoV0OaE5eZtOliAd7fNMIz01ETIESy0vkfGEElQg8TS201QHuNJ9J6fIxihdP2eRY+nYylGVqpL9nodHA9AAee8G13sSY8EuqeI9dlN2YAgVii1RQV6iRWqWZS8V8icAxLbRdTlGl/Gu5qRidWFaogKxUBeMBLdLrdGj8tlp47i8RmGsbg6l5EP0/O4QRafJRpEwFq5DAe1uuQsoHWqw5psem5lTBwl8i8AMtv6NtxIXuq6NCdoJXpp/oBJEXa1lu9Qc0SKvRIbPRhM1tKwUDf4nAIfW/omd4HOeHHei2j2PKKw08TctMKFWy3Jrf12H1R0ZkNZvwRucKwcJfYo8bhgnsZODzw7dx8doYq/S77g0qIMPuNKjLtCy3adUGrGswIvszM7b1SAw1Vz2EMyOeOY9nFuDApPBcJDrh4JuCslQB7X4Ny23GEQOymozI+cKCnf1SwVVXsKToDHrst+egs+3SDzdm/P7nFqEB3R7y9l0NzJVarKwxIvNjM7JPmWDtsqBowCIY+ksEjjj4Fd0+vegfuiUCd9ud6LOPYkKw5eWkw1FdooB+vw6pH+pZbl9pMiPnbAryL5jw+ZVawdJfIjB/vXElF3GSrp754NnG10DfiAPXx31QlKihKVfCfEjP9u26BgteP21EXqcFbw5QYQWpTRGYP5kfLOhAWF5XQCjf+Gh8MziFRVnL8MTWeDxti2dF9fJxHTZ8asCGZjNs3UYU96VTJuimCyARmImuPy63HaGra9F9TRzyXqr2J7coEL7tRURtl2PJDgWe261E/N5kJJUZkHcuHYWXVP61ME8Bwfwqx6mPXlOPxWl16Bi5xWBfX51C8dkWPLIxDhFb5Ii0yvHMjiQ8+1YSEvZqkbwvCZu/NGBXn5ldiXfhBvGYXeR0KNDMiNR6RK46ipDM5Qh9NRYPZ8ciPCcRi60yRNtkzNu4QhWSKxKwtd0IW28SLdxJufWydwRTEPDf8ng8eDw1jv5ZPE9expOHFNY9KsgopLqDBmQc1eO1Rj2s7S+hoj1XmLWwFgTPappCp8pdgaW7NFCUq5FSa4TpsBbrm3Q43LGP2XhmdrkkSQb/17oPvkcC/gLPZ5Rn6HFpXQAAAABJRU5ErkJggg==",
          "href": "https://ibm.webex.com/join/${emails}",
          "locator": "meeting"
        }
      }
    ],
    "services": [
      "Verse"
    ]
  }

3. Every time you change the extension code, reload the extension and then reload Verse so that the changes are picked up. For instructions on how to reload the extension click here.

   

Test it out

  1. Log in to Verse and hover on a Person bubble. The Sametime Chat service icon is replaced with the Jabber Chat icon. Click to launch Jabber Chat.
  2. Open any business card. The Sametime meeting service icon is replaced with the WebEx meeting icon. Click to launch WebEx.

Chat service GIF

Congratulations! You successfully configured a Chat service extension with Verse.

   

How it works

  1. The applications.json disables both Sametime Chat and meeting services via extension com.ibm.appreg.ext.disableSametime. If only want to disable Sametime meeting service, you can use extension com.ibm.appreg.ext.disableSTMeetings.
  2. Register a third-party Chat service via the following extension.
      {
     "type": "com.ibm.appreg.ext.templatedLink",
     "object": "com.ibm.appreg.object.person",
     "payload": {
       "text": "Jabber Chat",
       "icon": "data:image/jpeg;base64,...",
       "href": "xmpp://${emails}",
       "locator": "chat"
     }
      }
    
  3. Register a third-party Meeting service via the following extension.
      {
     "type": "com.ibm.appreg.ext.templatedLink",
     "object": "com.ibm.appreg.object.person",
     "payload": {
       "text": "WebEx meeting",
       "icon": "data:image/png;base64,...",
       "href": "https://ibm.webex.com/join/${emails}",
       "locator": "meeting"
     }
      }
    
  4. Click on the third-party chat or meeting icon to launch the chat or meeting service you registered.

Below are descriptions for the Third-party chat service extension.

Required Properties for a Chat Service extension
  • {string} type The acceptable value is com.ibm.appreg.ext.simpleLink or com.ibm.appreg.ext.templatedLink.
    • com.ibm.appreg.ext.simpleLink - It will use the registered href directly when contributing third-party chat in Verse. See more content in Simple Link extenson.
    • com.ibm.appreg.ext.templatedLink - It will replace the variable defined in href with user’s profile data. See more content in Templated Link extension.
  • {string} object The value must be com.ibm.appreg.object.person, which indicates this extension is targeted to business card.
  • {string} text The name of the third-party Chat or Meeting service. It will be displayed as tooltip when user hovers on the third-party Chat or Meeting icon.
  • {string} icon The icon for third-party Chat or Meeting extension. The only value format supported for this property is a data-uri with a base64 encoded payload.
  • {string} href The URL to open third-party Chat or Meeting service.
  • {string} locator A hint for container where to render the extension within the UI representation of the binding object. The supported value is chat or meeting.
    • chat - Integrate third-party Chat service.
    • meeting - Integrate third-party Meeting service.

   

Disable Sametime only

If you want to disable Sametime but do not want to register other alternative chat service, you can just register com.ibm.appreg.ext.disableSametime extension.

If you just want to disable Sametime meeting but keep Sametime chat, you can just register com.ibm.appreg.ext.disableSTMeetings extension. Notes that, you could NOT replace Sametime meeting with third-party meeting extension under this condition.

Third-Party File Repository Integration

This tutorial will get you started creating a third-party file repository extension for Verse. This is a follow-on tutorial to Your First Application for IBM Verse

There is much more detailed documentation available here, but it’s not required for completing the tutorial.


Create Third-Party File Repository Extension

   

Edit applications.json

1. Open src/applications.json in your text editor.

2. Append the following object into the array in applications.json, and save the file. Be sure to add a comma , at the end of the last object in applications.json before adding your own.

  {
    "name": "Third-party file repository integration",
    "title": "Third-party file repository integration",
    "description": "Integrate third-party file repository in Verse",
    "extensions": [{
      "type": "com.ibm.verse.ext.file",
      "name": "Third-party file repository extension",
      "payload": {
        "text": "Third-Party File Repository",
        "url": "https://third-party-file-repo.com",
        "icon": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAABGdBTUEAALGPC/xhBQAAAAlwSFlzAAAOxAAADsQBlSsOGwAAAGpJREFUOE+1k4EKgDAIRC36b/3z6kLJFUpOejAYQ293si3MvFMREdHdCQQqoN73rKpTxlxMC4BLpBrBg95NxV74QQ1De/LFQVSD89YMQBgBmPUsQuoAjbYi/ovgb80ctN9BO0JbYOo73xAdbuoHJPh854UAAAAASUVORK5CYII=",
        "renderParams": {
          "width": "450",
          "height": "230"
        }
      }
    }],
    "services": [
      "Verse"
    ]
  }

For the third-party file repository server, please see third-party-file-repo-integration as an example.

3. Every time you change the extension code, reload the extension then reload Verse, so that the browser and Verse will pick up your latest changes.

For instructions on how to reload the extension click here.

   

Test it out

  1. Login Verse, click the Compose button.
  2. In the New Message Dialog, the third-party file repository extension you registered is displayed in the toolbar.
  3. Click the repository extension button, to load the third-party file repository in a new window.
  4. Choose files in the repository to add file links into the message body.

The GIF animation for Third-Party File Repository Integration

Congratulations! You successfully configured a Third-Party File Repository extension with Verse.

   

How it works

  1. This step introduces a new extension point with the type com.ibm.verse.ext.file.
  2. A third-party file repository extension is contributed to Verse, a button is added on compose view toolbar.
  3. Click on the contributed button to arise third-party file repository
  4. Choose files from the repository.
  5. Verse receives the chosen files information and add the file links into the message body.