Customizing the Bookmark function in IBM Lotus Quickr 8.5 for Domino

Overview

Bookmarks can help users open their target documents quickly. Although IBM Lotus Quickr 8.5 for Domino (hereafter called Quickr Domino) itself does not have this function, it has a strong mechanism for customization and an open API that can realize the functions of Bookmarks.

First, Quickr Domino supports the creation of the link-type document that includes a URL value. After you open the document, it goes directly to the address pointed to by the URL, and you can redirect it to other documents, to achieve the Bookmarks function, by creating a link-type document.

Secondly, Quickr Domino uses the Dojo Dijit frame to develop its own widgets. By using this model, the server needs only to provide the data, while the client controls the modules and layout of the whole page.

In addition, Quickr Domino provides an extension mechanism that can use the widgets developed by the user or a third party. You need only to register a widget in the profile to replace the original widget of Quickr Domino.

Finally, Quickr Domino provides a set of open Services API that can be used to create, update, manage, or delete the contents and can be accessed to through the Simple Object Access Protocol (SOAP) or Representational State Transfer (REST).

For instance, we invoke the service of creating a link-type document by SOAP and achieve the WSDL document on the Quickr Domino server via the following URL: http://:/dm/services/ContentService?wsdl

Prerequisites

To get the most from this article, you should have basic knowledge of:

• Dojo Widget development and the event mechanism
• Web Services technology, including the WSDL regulations and the SOAP protocol
• JavaScript^TM Language

Application scenarios

Suppose we have a scenario in which Engineer Jia participates in many virtual teams that create many different folders to share the project documents in the same place. To get the latest information, Engineer Jia must switch back and forth between these folders. It is unfriendly and a waste of time.

With the Bookmarks function, however, Engineer Jia needs only to create a folder and set bookmarks for other documents in this folder, to reduce the time spent browsing different folders.

Quickr Domino supports the link-type documents and the bookmark functions in an indirect way. To see this, follow these steps:

1. Click the “New” drop-down menu and select “Link”, as shown in figure 1.

Figure 1. Create a Link document



2. On the Create New Link Page window (see figure 2), fill in three fields:
3. After completing these fields, click either the Save and Check in button or the Save as Draft link.

Figure 2. Create New Link Page window



Although Quickr Domino can use a Link document to realize the function of Bookmarks, it cannot provide a good user experience because the key URL cannot be achieved until you copy the address of the source document.

So let's try to customize the whole process so that it's more convenient to create the bookmark function. The customization steps are as follows:

1. First, in the WorkDocuments window, select “Bookmark” from the drop-down list under Project Schedule-Draft (see figure 3).

Figure 3. WorkDocuments window



2. In the “Bookmark to” pop-up window, select the “Inside a folder” option to create bookmarks, as shown in figure 4. The MyFavorites directory is used to store all the bookmarks.

Figure 4. “Bookmark to” window



3. Select the folder and click OK. A new Link document is created under the MyFavorites directory (see figure 5).

Figure 5. New Link document in MyFavorites



4. Click the document to directly open the source document pointed at by the bookmark (see figure 6).

Figure 6. Open source document



So, the Link document in Quickr Domino can be used to realize the function of bookmarks, and during the whole process, you need only open the source document and click the mouse a few times. The user experience is greatly improved.

Implementation steps

The steps to implement the functions are fairly straightforward:

(1) First, add an Item of Bookmark to the drop-down menu of the document.
(2) Create a dialog box to make it convenient to select the targeted directory.
(3) Develop a new event processing function to respond to the operations on the UI.
(4) Develop the new code to invoke the SOAP API to create a Link document and set up the URL to redirect to the active document.
(5) Finally, modify the profiles of Quickr Domino, and upload the customized widgets to replace the old ones.

In addition, some new character strings should be added to the resource document of Quickr Domino to meet the needs of the UI. Let's now go through the process step by step.

Extend widgets

In Quickr Domino 8.5, the Web UI consists of different widgets corresponding to Menu, Button, Dialog, and so on. You need to extend the UI for better supporting the Bookmark, modifying the resource document and adding new character strings to it. To do this follow these steps:

1. First, create a directory “qext\bookmarkWidgets” under DominoDir\data\domino\html\qphtml\skins. All the extension widgets are stored in this directory. DominoDir is the directory address installed by the client in Quickr Domino.
2. The Menu in Quickr Domino corresponds to the Widget “quickr.widgets.menu._pageMenu”. Create a new file “pageMenu_bookmark.js” under the “bookmarkWidgets” directory and add the code shown in listing 1.

Listing 1. Extend menu widget

3. Now we need to overload it and add the Bookmark option as well as a Menu parting line. Using the type of page as an example, you can see all the code in listing 2.

Listing 2. Overload the Menu via _populate


4. Add the code “this.addSeparator()” to create a parting line in the Menu
5. Then add the code this._addItem(“PAGE.ACTIONS_MENU.BOOKMARK”, dojo.hitch(this, “_bookmark”, this.unid, folderUNID)), where:

• the second parameter, dojo.hitch, returns a function that executes a given function in a given scope; in this case, it means that if a user clicks the “Bookmark” item in the menu, the function “_bookmark” will be executed, and

• this.unid and folderUNID are two parameters that are translated to the function “_bookmark”.

6. Now add new character strings to the “QuickrStrings.js” file under the directory “qphtml\skins\quickr\nls\en”, as shown in the listing 3.

Listing 3. Add the character strings “Bookmark”


The Multi-locale function of Quickr Domino 8.5 is used to switch between the different language versions of Quickr Domino. The resource files of these languages are all stored in their respective directories, under qphtml\skins\quickr\nls.

For instance, if the language setting of the browser is en, Quickr Domino will automatically upload the resource file “QuickrString.js” under the directory of en, and the Quickr Domino UI will be shown in English. When you add the new character string to the “QuickrString.js” file under the “en” directory, you still need to select “en” as the language of the browser to show it on the UI.

In Mozilla Firefox, you can choose the language, using Tools --- Options --- Content --- Languages, or set up the language of the browser based on your own needs, as long as the character strings are added to the correct QuickrString.js files.

The widget corresponding to the dialog that is used to change the position in Quickr Domino is quickr.widgets.misc._locator.

1. Create a file “locator_bookmark.js” under the “bookmarkWidgets” directory and add the code shown in listing 4 to it.

Listing 4. Extend dialog widget

2. In quickr.widgets.misc._locator, there is a “postCreate”way that is invoked after the creation of the Dialog. It can be used to initialize the UI of the Dialog, but you need to overload the postCreate, as shown in listing 5.

Listing 5. Overload postCreate


3. Now add a new comparison statement to the above code. If the value of action is bookmark, then read the corresponding value to FOLDER.CREATE.FIELDS.LOCATION.BOOKMARK_TO from the resource file “QuickrString.js” and demonstrate it as the title of the Dialog.

When Dialog is invoked by the Bookmark in Menu, the value of action can be set as bookmark through the event mechanism, and the character string “Bookmark to” can be added to the QuickrString.js file.

After inheriting the widgets from Quickr Domino and overloading the postCreate way of the UI to support the Bookmark functions, we have finished the customization of the UI and need only to customize the incident response.

Incident response

1. When customizing the Menu, add the following code:
2. Use the code in listing 6 to implement the “_bookmark” event in the pageMenu_bookmark.js file.

Listing 6. Implement “_bookmark” event


where:

• we invoke the way of doBookmarkPage from q_FolderUtils.copyMoveUtils and send the parameters such as unid, folderUnid, and name.

• q_FolderUtils.copyMoveUtils belongs to the utility class, which can be used to implement the operations of copying folder, moving folder, copying page, moving page, etc.

3. We also realize the function processing of Bookmark in this utility class, naming it doBookmarkPage and adding the code in listing 7 to the folderutils.js file under the qhmtml\widgets\common directory.

Listing 7. Implement doBookmarkPage


The above code was written based on the mechanism of event publishing and subscribing in Dojo. The connections between different event invoking and responding ways can be established by this mechanism. Take the following code as an example:
where the first parameter of “publishEvent” way is used to publish the ACTION.CHANGELOCATION.OPEN event, and the second parameter is an event parameter.

After the event is published, all the objects that have subscribed to this event will receive the message and implement the processing. In the “qphtml\widgets\popupcontroller.js” file, the code is written as follows:
The way of subscribeEvent can be used to subscribe to an event. Its first parameter represents the subscribed event’s name, while the second parameter demonstrates the processing way of the event. After the CHANGELOCATION.OPEN event is published, all the quickr.widgets._popupcontroller ways that subscribed to this event will implement the way of __changeLocation.

In the way of doBookmarkPage, we not only publish the event but also subscribe to the event:
In the way of subscribeEvent, the second parameter is an anonymous function. After the ACTION.CHANGELOCATION.OK event is published, this anonymous function will be implemented to define the two callback functions, bookmarkError and bookmarkDone.

These can be used, respectively, to handle the failure and successful operations of Bookmark before invoking the bookmark function of
The Bookmark function can be used to invoke the Web Services API of Quickr Domino to create the link document. To do this:

1. Add bookmark to the “qphtml\widgets\common\docfolderutils.js” file as shown in listing 8.

Listing 8. Implement bookmark


The most important part of bookmark is to construct the SOAP message which, in the above listing, uses to create a draft document, including a element designating the absolute path to create the draft. This absolute path consists of the place name, the room name, the folder ID, and the draft name. Its format is:

/@P{PlaceName}/@R{RoomName}/@F{FolderID}[/@F{FolderID}]/{DocumentName}

We can use multiple @F{FolderID}'s to identify the nested situation of folder. Because the directory “MyFavorities” is created in Library, we need two @F's to show the absolute path of Draft. As a default folder of Quickr Domino, Library has the following fixed ID:

CD0EF97D625305B90525670800167213

Both the name of the bookmark and the dName parameter should be the same as the name of the source document. Thus we can directly use the bookmark in Path.

is a complex element that includes , < propertySheets>, and other elements. The element is used to designate the type of document to be created with an ID of _Pplace_RMain_D256C05A2026AE284052568B0005C0B6D, composed of the place name, the room name, and the document type ID, whose format is in _P{PlaceName}_R{RoomName}_D{DocumentTypeID}.

Among these, DocumentTypeID is the most important. The LinkDocumentTypeID is 256C05A2026AE284052568B0005C0B6D.

The element includes two elements, whose profiles are h_URLpointer and h_URLNewWindow, corresponding to the two respective fields in LinkDocumentType, where:

• h_URLpointer represents the URL redirected to when the LinkDocument is opened. The value of h_URLpointer is ?OpenDocument#{unid=' + dUnid + '}, demonstrating how to open the document directed by unid under the URL of the current page. dUnid represents the ID of the document to be bookmarked,

• h_URLNewWindow represents whether or not to open the document from a new window, Yes or No.

After the SOAP message is constructed, Quickr Domino handles the rest of the work, sending the SOAP message to the server by asynchronous calls and showing the results on the UI.

The reason we create the SOAP API of Draft is because Quickr Domino is a collaborative platform on which many people can work together. The Draft is visible only to its creator, so no one else can see this bookmark, and the privacy of users is thus protected. If the user wants to share this bookmark, all he/she needs to do is to check in the operation.

Register widgets

In the above steps, we extended our own widgets, including the UI and the incident response, and created the LinkDocument through the SOAP API provided by Quickr Domino. Now we need to register these customized widgets in Quickr Domino to replace the original ones.

Quickr Domino offers a convenient mechanism to do the registration. By redefining the widget used in Quickr Domino through the registered file WidgetRegisterConfig_ext.js, we can find this file under the qphtml\widgets\resources directory. When Quickr Domino is started, it will upload the designated widgets in the file and replace the old ones according to the requirements.

The content of WidgetRegisterConfig_ext.js is shown in listing 9.

Listing 9. Register widget

{

registerWidgets:

[

//Register the Modul Path

{
type:  'REGISTERMODULEPATH',

name:  "qext",

path:  "/qphtml/skins/qext"

},

//BOOKMARK Menu Widget

{
type: 'globalreplace',

source: 'quickr.widgets.menu.pageMenu', 		use: 'qext.bookmarkWidgets.pageMenu_bookmark'

},

//BOOKMARK Dialog Widget

{
type: 'globalreplace',

source: 'quickr.widgets.misc.locator',

use: 'qext.bookmarkWidgets.locator_bookmark'}

]

}

Here, the REGISTERMODULEPATH type can create a shortcut directed to the location of the customized widgets and includes Path and Name, representing the location of the widgets and one name of the location, respectively.

Another type is the globalreplace. When you use this type, the new widgets will replace all the old used widgets.

The Source includes the link of the widget that needs to be replaced, and the Use directs to the new link of the widget.

Use qext.bookmarkWidgets.pageMenu_bookmark to replace quickr.widgets.menu.pageMenu, and qext.bookmarkWidgets.locator_bookmark to replace quickr.widgets.misc.locator.

For the sake of performance, Quickr Domino uses the compressed JavaScript files by default. However, when we are customizing the widgets the uncompressed files are modified, so to bring the customization into effect, we must modify the qpconfig.xml configuration file, setting the enabled property of qwidgets to false (see listing 10).

Listing 10. Modify the qpconfig.xml file

<!-- =============== START OF SAMPLE =================-->

<qdojo enabled="true" />

<qwidgets enabled="false" />

<qstyles enabled="true" />

<!-- =============== END OF SAMPLE =================== -->

After the server is restarted, Quickr Domino uploads the uncompressed files. The customization work is now finished.

Conclusion

This article has provided a brief introduction to the Bookmark functions and explained how to customize widgets (including the UI and the incident response), how to register and use the widgets, and how to use the SOAP API to create a Link-type document. By gaining a better understanding of Quickr Domino customization and its strong functions, you can customize other applications.

Resources

• Dojo toolkit
• Lotus Quickr wiki
• Extending the Widget Registry
• IBM Lotus Quickr Web Services

About the author

Tao YT Yan is a Software Engineer based at IBM's China Development Lab in Beijing, where he works on the Lotus Quickr for Domino product and is responsible for Domino Document Management customer support.