How to extend Notes 8: coupling LiveText to a Java action

I get so many question on how to extend Notes 8 that I finally decided to create a series of blog posts on how to do it. All the posts in the series may be found under the extending_notes8 tag. In all of the examples I assume a working knowledge of Eclipse and Java programming and how to work with extension points.

For this second post I’ll touch on one of my favorite features of Notes 8 that is MyWidgets and LiveText. From the user interface you may create a number of widget types (web, Notes etc.) that act on text which is automatically recognized and highlighted by Lotus Notes using the LiveText feature. But what if you wanted to perform an action that didn’t lend itself to one of these widget types? What if you wanted to couple the text recognized by LiveText to a Java action? Well look no further. In this post I’ll show you how to combine the org.eclipse.ui.popupMenus extension point with a com.ibm.rcp.content.IDocumentContent object contribution to do what is transparently done using MyWidgets.

Let me preface this by saying that it’s still far easier to do this using MyWidgets but still this isn’t rocket science.

To accomplish this task you’ll need two pieces. First of you need the code to execute. This is done using an action class that implements org.eclipse.ui.IObjectActionDelegate which means that you need to implement three methods:

  • public void setActivePart(IAction action, IWorkbenchPart part)
    Called when what’s called the part is changed in Eclipse. You can leave this method blank.
  • public void selectionChanged(IAction action, ISelection selection)
    Called when you run an action on some text that the client highlighted using LiveText. The purpose of this method is to extract the text and make it available to the run method (see below).
  • public void run(IAction action)
    This is the workhorse of the class and it’s called whenever the action is selected from the context menu. The action will act on the text you extracted in the selectionChanged method.

The run-method isn’t as interesting as it just performs the action. The method is called in the UI thread. The selectionChanged-method is more fun as this is where you extract the highlighted text. The example here acts on a recognized phone number but it could just as well have been another of the built in recognizers. Below is a snippet of code on how to get the highlighted text.

public void selectionChanged(IAction action, ISelection selection) {
   IDocumentContent doc = null;

   // cast/adapt selection
   if (selection instanceof StructuredSelection) {
      Object sel = ((StructuredSelection)selection).getFirstElement();
      if (sel instanceof IDocumentContent) {
         doc = (IDocumentContent)sel;
      }
   } else if (selection instanceof IDocumentContent) {
      doc = (IDocumentContent)selection;
   } else {
      // try and adapt
      IAdapterManager amgr = Platform.getAdapterManager();
      doc = (IDocumentContent)amgr.getAdapter(selection,
          IDocumentContent.class);
   }
   if (null == doc) {
      this.selection = null;
      return;
   }

   // get number from document property
   this.selection = doc.getProperties().getProperty("phone");
}

The second piece to the puzzle is the plugin.xml snippet that couples our action to the LiveText feature of Lotus Notes. It’s again a org.eclipse.ui.popupMenus extension point coupled to an object contribution but this time also a visibility modifier to only show the action when text matching a recognizer is shown. You will want to pay attention to the italic text. Again you will need to change the class name for the action as well.

<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.4"?>
<plugin>
  <extension point="org.eclipse.ui.popupMenus">
    <objectContribution
          id="com.lekkimworld.livetext.objectContribution2"
          objectClass="com.ibm.rcp.content.IDocumentContent">
       <action
             class="com.lekkimworld.livetext.Action1"
             id="com.lekkimworld.livetext.action2"
             label="Call it!">
       </action>
       <visibility>
          <and>
             <objectState name="content.type" value="content.phone" />
             <objectState name="contents" value="*" />
          </and>
       </visibility>
    </objectContribution>
  </extension>
</plugin>

Easy isn’t it??

In a future post in this series I’ll show how to act upon the other built in recognizers and how to act on your own. Stay tuned…

How to extend Notes 8: coupling text selection to Java action

I get so many question on how to extend Notes 8 that I finally decided to create a series of blog posts on how to do it. All the posts in the series may be found under the extending_notes8 tag. In all of the examples I assume a working knowledge of Eclipse and Java programming and how to work with extension points.

For this first post I’ll touch on one of my favorite features of Notes 8 that is MyWidgets and LiveText. From the user interface you may create a number of widget types (web, Notes etc.) that act on selected text but what if you wanted to perform an action that didn’t lend itself to one of these widget types? What if you wanted to couple text selection to a Java action? Well look no further. In this post I’ll show you how to combine the org.eclipse.ui.popupMenus extension point with a org.eclipse.jface.text.ITextSelection object contribution to do what is transparently done using MyWidgets.

Let me preface this by saying that it’s still far easier to do this using MyWidgets but still this isn’t rocket science.

To accomplish this task you’ll need two pieces. First of you need the code to execute. This is done using an action class that implements org.eclipse.ui.IObjectActionDelegate. This means you need to implement three methods:

  • public void setActivePart(IAction action, IWorkbenchPart part)
    Called when what’s called the part is changed in Eclipse. You can leave this method blank.
  • public void selectionChanged(IAction action, ISelection selection)
    Called when you select some text in the Notes client and select your action. The purpose of this method is to extract the selected text and make it available to the run method (see below).
  • public void run(IAction action)
    This is the workhorse of the class and it’s called whenever the action is selected from the context menu. The action will act on the selected text you extracted in the selectionChanged method.

The run-method isn’t as interesting as it just performs the action. The method is called in the UI thread. The selectionChanged-method is more fun as this is where you extract the selected text. Below is a snippet of code on how to do it.

public void selectionChanged(IAction action, ISelection selection) {
   StructuredSelection sel = (StructuredSelection)selection;
   try {
      IAdapterManager amgr = Platform.getAdapterManager();
      Object obj1 = sel.getFirstElement();
      Object obj2 = amgr.getAdapter(obj1, ITextSelection.class);
      if (obj2 instanceof org.eclipse.jface.text.ITextSelection) {
         ITextSelection txtSelection = (ITextSelection)obj2;
         this.selection = txtSelection.getText();
      }
   } catch (Throwable t) {
      this.selection = null;
   }
}

The second piece to the puzzle is to tell the platform when you would like your action to be listed ie. when select is selected. This is done in the plugin.xml using the org.eclipse.ui.popupMenus extension point and by doing an object contribution as shown below. The italic text (the id’s and the action label) may be changed to your liking. The bold/italic text is the class name of your action which should be changed to match your action class.

<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.4"?>
<plugin>
   <extension point="org.eclipse.ui.popupMenus">
      <objectContribution
            id="com.lekkimworld.textsel.objectContribution1"
            objectClass="org.eclipse.jface.text.ITextSelection">
         <action
               class="com.lekkimworld.textsel.SelectionAction"
               enablesFor="*"
               id="com.lekkimworld.textsel.action1"
               label="Perform action from selected text">
         </action>
      </objectContribution>
   </extension>
</plugin>

The next post (which will be published tomorrow) will show you how to act upon LiveText that is couple your Java action to text that the Notes client recognizes and highlights for you. Stay tuned…