ShowTable of Contents
Overview
IBM® Lotus® Quickr® version 8.5 offers an unprecedented user experience, with more Web 2.0, more simplicity and convenience to operate. The new architecture makes the customization of the product easier and more flexible. For more information about the basic approach of Quicker 8.5 customization, please refer to the
IBM Lotus Quickr wiki.
This article focuses on how to add the tag function to Lotus Quickr 8.5, using many customization-related technologies, and can be used as a reference for developers. We discuss how the tag function extends the functions of the product, makes it easier to find documents, and provides users with a more cooperative social experience.
Prerequisites
To get the most from this article, you should have
- Good Lotus Domino application development skills
- A good knowledge of Web development techniques such as HTML and JavaScript®
- Familiarity with the Dojo framework, as well as the development of Dijit widgets
System architecture
Unlike in earlier versions of the product, Lotus Quickr 8.5 displays its page and implements its functions with extensive use of Dojo-based widgets, the advantage of which is that the client and server functions can be totally separated.
The page display can be done by the widgets at the client side, while the server side is responsible only for providing the data to the client. Thus, without any extra work, the pressure on the server side is reduced.
Obviously our customization development work will be much easier based on this framework because we need only to add or modify the client’s script code. In figure 1 you can see how the Quickr library page is composed of widgets.
Figure 1. Quickr library page
The whole page is composed of several components placed in different positions, similar to the SkinComponent elements used in the earlier Quickr versions. However, they are more flexible and easier to write and customize, so that users can change the page layout by relocating the components.
Figure 2 shows an example of the working mechanism of one of the widgets, clearly illustrating why Lotus Quickr 8.5 is more Web 2.0; specifically, the client- and server-side functions are totally separate, and the system architecture is more straightforward.
Figure 2. Widget working mechanism
Before starting the customizing work, we need to identify the two Quickr extension files, so we can add custom codes to them. These files do not contain anything initially, and thus the codes will not be overwritten during the product upgrading. They also can be seen as the entrance to Quickr customization (see table 1).
Table 1. Extension files and their description
File | Description |
<Data>\domino\html\qphtml\widgets\resources\widgetRegistryConfig_ext.js | Widget registry file. All the components (widgets) must be registered in this file before usage. If you want to replace the components with your own developed ones, you must specify them in this document. |
<Data>\domino\html\qphtml\skins\quickr\scripts\Quickr_ext.js | Script extension file. The file will be loaded automatically when you open any Quickr page, and all scripts inside will be executed. |
where “<Data>” is the Domino Data directory.
Goals
One of our goals is to add a “Tag” field the Upload File dialog box, so that users can add tags to the uploaded files (see figure 3).
Figure 3. Tag field added to the Upload File dialog
Another goal is to add a Tags section below the left-hand navigation pane of the Quickr window in which all tags are shown. When you click one of them, you can see a list of all the same tagged files on the page, as shown in figure 4.
Figure 4. Tag section and the list of files classified by the specified tags
Steps
Here we discuss the step-by-step instructions.
Step 1: Create and register the components
All the customized codes are contained in the .zip file attached to this article. You can download them to your computer and follow the steps below to deploy. The Appendix section provides explanations of several of the more important files.
- On the Quickr home page, create a new Place, for example, “TagPlace”.
- Download the attached compressed files and extract them into a local directory.
- Copy the “custom” folder to <Data>\domino\html\qphtml\skins\ (where <Data> is the Domino Data folder), after which the directory structure should be: <Data>\domino\html\qphtml\skins\custom\widgets\tag\...
- Copy widgetRegistryConfig_ext.js under the custom folder to <Data>\domino\html\qphtml\widgets\resources\ to replace the original documents.
- Copy Quickr_ext.js under the custom folder to <Data>\domino\html\qphtml\skins\quickr\scripts\ and replace the original one.
Step 2: Increase a Tag field to Upload form
To save a Tag that was inputted by a user in the Upload File dialog box into the database, first we need to add a Tag field to the Upload form as follows:
1. Using Lotus Notes®, open the place database, i.e. main.nsf, open the “System\QDK” view, and then select the document with the following criteria:
- The value of its h_Type column is “h_Field”,
- The value of h_SystemName column is “h_Name”,
- The value of its Title column is “@@[TAILOR_H.LABEL_SINGLEUPLOADFORMPAGENAMEFIELD]@@”
Figure 5. Select the designated documents in database
2. Select Edit – Copy from the menu bar, and then select Edit – Paste. This creates a new document from the selected one (see figure 6).
Figure 6. Copy to create new document
3. Double-click the newly created document to open it. There are several values that need to be modified, listed in table 2 and shown in figures 7 and 8.
Table 2. Values to modify
FieldName | Value |
h_Name | Tag: |
h_SystemName | h_Tag |
h_FieldType | h_TextInput |
h_FieldFormat |
|
h_FieldIsRequired |
|
h_Position | 400 |
Figure 7. Modify the basic information about the document
Figure 8. Modify the location information about the document
4. Save the modifications and close Lotus Notes.
Step 3: Create two views
In the place database, we need to create two views that can be used to list all the tags, and the documents classified by these tags, respectively. The two views will be called by the client-side script code, and the returned data will be displayed on the Web page.
1. Using Domino Designer, open the place database, main.nsf. Click the New View button to create a new view named DocsByTag|h_DocsByTag whose Query condition is SELECT h_Tag != "" (see figure 9).
Figure 9. DocsByTag Create View window
2. Open the new DocsByTag view and add three columns, “h_Tag”, “h_Title”, and “h_LastEditor” to it. The parameter settings of the h_Tag column are listed in table 3 and shown in figure 10.
Table 3. Parameter settings of the h_Tag column
Name | Value |
Title | h_Tag |
Programmatic Name | $h_Tag |
Value (Formula) | list := @Explode(h_Tag;",");
@Transform(list; "tag"; @Trim(tag)) |
Categorized | Yes |
Show multiple values as separate entries | Yes |
Case sensitive sorting | No |
Figure 10. Values in the h_Tag column
Figure 11 shows the property settings of the h_Tag column.
Figure 11. Property settings of the h_Tag column
The parameter settings of h_Title column are listed in table 4.
Table 4. Parameter settings of h_Title column
Name | Value |
Title | h_Title |
Programmatic Name | $h_Title |
Value (Formula) | h_Name |
The parameter settings of h_LastEditor column are listed in table 5.
Table 5. Parameter settings of h_LastEditor column
Name | Value |
Title | h_LastEditor |
Programmatic Name | $h_LastEditor |
Value (Formula) | @If(@IsAvailable(h_LastEditorDisplayName);h_LastEditorDisplayName;"") |
3. Click the New View button to create another view named Tags|h_Tags whose Query condition is SELECT h_Tag != "" (see figure 12).
Figure 12. Tags Create View window
4. Open the newly created Tags view and add the column “h_Tag” to it. Table 6 lists the parameter settings of h_Tag column.
Table 6. Parameter settings of h_Tag column
Name | Value |
Title | h_Tag |
Programmatic Name | $h_Tag |
Value (Formula) | h_Tag |
5. Save the modifications and close Domino Designer.
Step 4: Create a display document
Our customization work is nearly completed. All the necessary scripts and views have been created and deployed; now we only need to create a document for display through the Quickr Web UI.
- Open the previously created place within the browser.
- Click the Customize button on the top right-hand side of the page and select “Form” from the pop-up dialog box.
- Click the New Form button on the subsequent page to create a form:
- Input a name for the form, for instance, “Tag Form”.
- Click the Add button (next to the Form Contains field), select the fieldtype of “Plain Text”, and click Next.
- Enter “UsedForTag” and “true” in the “What is the title of this field?” and What is the initial value? fields, respectively, as shown in figure 13. (Note: You cannot fill in these two columns with other values); click Next to save the modifications.
Figure 13. Add the field of “UsedForTag”
4. Make sure the created form is the same as that shown in figure 14; click Complete.
Figure 14. Edit Form window
5. Next, we create a document based on the Tag Form to show the list of documents that are classified by the tags. To do this, select Index from the left-hand navigation pane of the Quickr home page, click “Place Actions,” and select New – Tag Form from the drop-down menu (see figure 15).
Figure 15. Create a document based on the Tag Form
6. Input any string as the document name, such as “Documents By Tag”, keep the value of the UsedForTag field as “true”, and click Save.
7. The last step is to inform the customized codes of the UNID of the display documents. Open the newly created document within the browser, find the UNID parameter in the location bar, and write it down (see figure 16).
Figure 16. Record the UNID of the new document
8. Open the Quickr_ext.js file from
\domino\html\qphtml\skins\quickr\scripts\, find docsByTagID: "92D304084E32EC36862577C0002CD1DE", and change the value of “docsByTagID” to the value of the UNID; click Save. Our customization work is now finished.
Checking the results
Now it's time to check the results, before which we suggest you empty the browser cache to prevent the scripts from being cached:
- Click Upload in the Quickr document library; you will see the Tag column in the pop-up dialog box. Upload a document and add tags to it (separating multiple tags by commas) and save the document.
- When the new tags are shown in the Tag section on the left-hand side of the page, you can click one of them to see the result.
- Save the customized place as a template, so then you can create multiple places with Tag functions based on the template.
Appendix: Code descriptions
- Quickr_ext.js. A widget named “custom.widgets.tag.quickrTag” was developed to display a Tag section below the left-hand navigation pane. To make sure it can be loaded correctly, you must create an instance of this widget in the Quickr_ext.js file and add it to the specified position on the page. The code is shown in listing 1.
Listing 1. Quickr_ext.js code
dojo.addOnLoad(function(){
dojo.require("custom.widgets.tag.quickrTag");
var tagDiv=new custom.widgets.tag.quickrTag()
.placeAt("lotusColLeft");
});
- widgetRegistryConfig_ext.js. In this file, you need to inform Lotus Quickr where the new widgets reside and which system widgets will be replaced, and under what conditions this replacement will occur (see listing 2).
Listing 2. widgetRegistryConfig_ext.js code
{
registerWidgets:
[
{
type:'RegisterModulePath',
name:'custom.widgets',
path:'/qphtml/skins/custom/widgets'
},
{
type:'GlobalReplace',
source:'quickr.widgets.page.modalPageDialog',
use:'custom.widgets.tag.modalPageDialog'
},
{
type:'GlobalReplace',
source:
'quickr.widgets.page.defaultUploadDialog',
use:'custom.widgets.tag.defaultUploadDialog'
},
{
type:'Page',
condition:
'object.entry.fields.c_UsedForTag=="true"',
use:'custom.widgets.tag.docsByTag'
}
]
}
- modalPageDialog.js. Defines the new uploading dialog box widget, “custom.widgets.tag.defaultUploadDialog”, which replaces the original dialog box of the Quickr widget, “quickr.widgets.page.modalPageDialog” according to the configuration in widgetRegistryConfig_ext.js.
Pay attention to the parameter “xsl” in createParms and editParms, since they point to the .xsl files that are used in the creating and editing mode by the current widget. Both these .xsl files are customized (see listing 3).
Listing 3. modalPageDialog.js code
dojo.provide
("custom.widgets.tag.modalPageDialog");
dojo.require
("quickr.widgets.page._modalPageDialog");
dojo.declare
("custom.widgets.tag.modalPageDialog",
[quickr.widgets.page._modalPageDialog],
{
createParms: {
xsl: "defaultUpload_create.xsl",
formName: "",
title: ""
},
editParms: {
xsl: "defaultUpload_edit.xsl",
formName: "",
title: ""
},
……
}
);
- defaultUpload_create.xsl. All the necessary code for displaying the Upload dialog box is included in this file. Notice that it looks like HTML. In Quickr 8.5, the method of XML + XSL -> HTML is used to show the page; as a result, the XSL files are responsible for displaying pages. Can you find the span tag in listing 4? It was added to implement the function of tag input box.
Listing 4. defaultUpload_create.xsl code
<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:output method="html" encoding="utf-8" />
<xsl:param name="WIDGETID_PARAM"
select="'*DEFAULTWIDGETID*'"/>
<xsl:param name="FOLDER_UNID" select="''" />
<xsl:param name="DIALOG_ID"
select="'*DIALOG_ID*'"/>
<xsl:template match="/">
<xsl:for-each select="entry">
<form name="CreateUpload" class="lotusForm"
method="post" onsubmit="return false;"
enctype="multipart/form-data">
<fieldset>
<div id="singleUpload">
……
<!--title/h_Name-->
<span
dojoType="quickr.widgets.page.field.text"
label="PAGE.CREATE.FIELDS.NAME.LABEL"
state="edit"
className="lotusText"
name="tempTitle"
targetid="{$DIALOG_ID}_title"
value=""
isRequired="true"
bUpload="true"
width="440px"
pageWidgetId="{$WIDGETID_PARAM}"
></span>
<!--tag-->
<span
dojoType="quickr.widgets.page.field.text"
label="Tag"
state="edit"
className="lotusText"
name="h_Tag"
targetid="tag"
value=""
isRequired="false"
bUpload="true"
width="440px"
pageWidgetId="{$WIDGETID_PARAM}"
></span>
……
</div>
</fieldset>
</form>
</xsl:for-each>
</xsl:template>
</xsl:stylesheet>
- docsList.js. This file is used to show the list of documents that are classified by the tags. The PostCreate function is its entrance. It will invoke the loadDocsByTag function, in which the Ajax Engine of Dojo is used to retrieve data from the server. The ShowDocsByTag function is then used to handle the returned data and display the result (see listing 5).
Listing 5. docsList.js code
dojo.provide("custom.widgets.tag.docsList");
dojo.require("quickr.widgets.view._base");
dojo.declare("custom.widgets.tag.docsList",
[quickr.widgets.view._base],
{
postCreate: function() {
var tag =
window.q_GeneralUtils.getParameterFromUrl("tag");
if (tag) {
var div = dojo.byId("tagTitle");
div.innerHTML =
"Selected Tag: <b>" + tag + "</b>";
this.loadDocsByTag(tag);
} else {
var div = dojo.byId("tagCotent");
div.innerHTML = "Please select one tag!";
}
},
loadDocsByTag: function (tag){
var oWidget = this;
this.ajax.get (
{
url: TagUtil.loadDocsByTagUrl +
"&RestrictToCategory=" + tag,
preventCache: true,
timeout: 3000,
handleAs: "xml",
load: function (response, ioArgs) {
oWidget.showDocsByTag(response);
}
}
);
},
showDocsByTag: function (response) {
……
},
……
}
);
- quickrTag.js. This file displays the Tag section below the left-hand nav pane. Its process is similar to the transference process of functions in docsList.js. The LoadTag function first retrieves data from the server, and then the showTag function handles the data and displays the result.
Pay attention of the system event “ACTION.MESSAGE.CONFIRM” that has been subscribed by this widget. The purpose is to confirm that the Tag section can be refreshed in time to show the newly added tags, whenever a new document is created or modified (see listing 6).
Listing 6. quickrTag.js code
dojo.provide("custom.widgets.tag.quickrTag");
dojo.require("quickr.widgets._base");
dojo.require("quickr.widgets._event");
dojo.declare("custom.widgets.tag.quickrTag",
[quickr.widgets._base, quickr.widgets._event],
{
templateString: "<div></div>",
postCreate: function() {
this.loadTags();
this.subscribeEvent
(this.ACTION.MESSAGE.CONFIRM, "loadTags");
},
uninitialize: function() {
this.unsubscribeEvent
(this.ACTION.MESSAGE.CONFIRM);
},
loadTags: function (){
var oWidget = this;
this.ajax.get (
{
url: TagUtil.loadTagsUrl,
preventCache: true,
timeout: 3000,
handleAs: "xml",
load: function (response, ioArgs) {
oWidget.showTags(response);
}
}
);
}，
showTags: function (response, ioArgs) {
……
}
}
);
Conclusion
This article has explained how to add the Tag function to Lotus Quickr for Domino 8.5, and serves as a good reference about Quickr customization in general.
Resources
About the author
Yin, Zhiyong is a Software Engineer based at IBM's China Development Labs in Beijing. He has a deep understanding of Quickr customization and is interested in social software.