Customizing and migrating to IBM Lotus Quickr 8.

5 for Domino
Zheng Fei Guo (guozf@cn.ibm.com) Software Engineer IBM Collaboration Solutions IBM Software Group Beijing 11, China Xu Wang (wangxu@cn.ibm.com) Software Architect IBM Collaboration Solutions IBM Software Group Beijing 11, China June 2011 Copyright International Business Machines Corporation 2011. All rights reserved. Summary: This white paper explains the details you need for customizing IBM Lotus Quickr 8.5 for Domino and provides guidelines and tips on how to migrate Team Places from the Quickr v8.2 theme to the v8.5 theme. We focus on how the Quickr 8.5 theme works and explain the differences between the 8.2 and 8.5 themes.

Table of Contents
1 Introduction...............................................................................................................................2 2 Anatomy of the Quickr 8.5 theme..............................................................................................3 2.1 Page structure...................................................................................................................3 2.2 Files...................................................................................................................................4 3 What's new in the Quickr 8.5 for Domino theme.......................................................................5 3.1 Page layout.......................................................................................................................6 3.2 Widgets.............................................................................................................................8 3.3 Widget registry................................................................................................................10 3.4 AJAX and XSL................................................................................................................15 3.5 Event model....................................................................................................................16 3.6 Upgrade to use Dojo 1.3.2..............................................................................................18 3.7 Localized style sheets and string-resource files..............................................................18 3.8 New qpconfig.xml settings pertaining to customization...................................................20 4 Creating a custom theme........................................................................................................21 4.1 Getting started.................................................................................................................21 4.2 Creating your theme........................................................................................................21 4.3 Creating a template (PlaceType) using your theme.........................................................30 1

5 Customizing forms..................................................................................................................30 5.1 Creating new forms.........................................................................................................30 5.2 Migrating a v8.2 form to v8.5...........................................................................................30 6 Customizing widgets...............................................................................................................38 6.1 Sample custom themes for Quickr 8.5 for Domino..........................................................38 6.2 Changing footer links......................................................................................................39 6.3 Switching from CKEditor to other rich text editors...........................................................39 6.4 Customizing Action buttons.............................................................................................40 6.5 Customizing menu items.................................................................................................41 6.6 Adding a slideshow view..................................................................................................41 6.7 Inline attachments...........................................................................................................43 6.8 Adding a Java applet for uploading files to a place..........................................................44 6.9 Embedding an XPages Notes database into a Quickr for Domino place.........................45 6.10 Tag cloud.......................................................................................................................45 6.11 Using the Quickr event system......................................................................................46 6.12 Delivering Quickr 8.5 customization widgets via templates...........................................46 7 Migrating customized templates to the 8.5 theme...................................................................46 7.1 Migrating htmls and CSS (theme related).......................................................................47 7.2 Migrating JavaScripts and customized forms..................................................................47 7.3 Using 8.2 unchanged customizations on an 8.5 server...................................................53 8 Quickr for Domino hooks........................................................................................................53 8.1 Server event hook...........................................................................................................53 8.2 JavaScript hook...............................................................................................................54 9 Other customizations..............................................................................................................57 9.1 Customizing notifications.................................................................................................57 9.2 QPAPI.............................................................................................................................57 10 General tips and precautions................................................................................................57 11 Conclusion............................................................................................................................58 12 Resources.............................................................................................................................58 About the authors......................................................................................................................58

1 Introduction
Lotus Quickr 8.5 for Domino is an important release that is based on new framework. The purpose of this paper to help users understand the new 8.5 framework, how to customize Quickr 8.5, and how to migrate existing templates. This paper also explains how to customize notifications and provides a high-level description of the usage of event hook interfaces and Placebots. Some samples are included to enhance your understanding and as best practices. To get the most from document, you should have some basic knowledge of HTML, cascading style sheets (CSS), and JavaScript. In addition, you should read the IBM Redbooks publication, Customizing QuickPlace, which gives some basic background about Quickr for Domino customization.

2 Anatomy of the Quickr 8.5 theme

Before drilling down into the details of the v8.5 user interface (UI) architecture, implementation, and extension mechanism, let's cover some of the elements that make up the Quickr 8.5 theme.

2.1 Page structure

Figure 1 shows the page structure of the common UI framework, below which are listed the classes and IDs of the main components on the page in table 1.
Figure 1. Page structure of common UI

Table 1. Classes and IDs of the main page components

Classes
lotusFrame lotusBanner lotusTitleBar lotusPlaceBar lotusMain lotusColLeft lotusContent lotusFooter

IDs
Top level container Contains branding and global links Contains application links and search Contains place name (link) and Place Actions, Customize button. Contains the page columns Optional, contains menu Contains main content Contains helper links

Figure 2 shows the Library page in the 8.5 theme.

Figure 2. Library page in 8.5 theme

2.2 Files
All files comprising the Quickr 8.5 theme reside on the Lotus Quickr server, in or under the path qphtml/skins/quickr and qphtml/widgets (see table 2). NOTE: Unless otherwise indicated, all path names mentioned in this paper are relative to the top-level Domino html path, domino/data/domino/html.
Table 2. Quickr 8.5 theme files

File
page.htm

Location
qphtml/skins/quickr

Description
The main theme layout used when viewing pages and documents, and so on. It positions the main Quickr widgets. Used for page layout (only used in Members page, an 8.2 theme remnant). Used for page layout (used in Folder Properties, Customize and Offline pages, 8.2 theme remnants). Unused, but available for use in an Quickr 8.5based custom theme. Theme-specific, localized style sheet. It includes the Lotus oneui V2 css. The bidi (bidirectional) style sheet. Contains all Quickr for Domino widgets.

listfolder.htm edit.htm

qphtml/skins/quickr qphtml/skins/quickr

Stylesheet.css qstyles.css qstylesRTL.css qwidgets.js

qphtml/skins/quickr qphtml/skins/quickr/theme qphtml/skins/quickr/theme qphtml/skins/quickr/scripts

Quickr.js qdojo.js Quickr_ext.js QuickrStrings.js *.js *.xsl

qphtml/skins/quickr/scripts qphtml/skins/quickr/scripts qphtml/skins/quickr/scripts qphtml/skins/quickr/nls qphtml/widgets qphtml/widgets

Theme-specific JavaScript support. Used in page.htm. A Dojo package used in Quickr for Domino for performance purposes. Available for use in a Quickr 8.5-based custom theme. Theme-specific, localized strings Separate widget. qwidgets.js packs all of the widgets under this folder. XSL file used in 8.5 theme.

3 What's new in the Quickr 8.5 for Domino theme

Those of you who are former Lotus Quickr 8.2 or QuickPlace users are familiar with the structure of, and methods for, customizing the themes provided in these earlier offerings. For those users, the Quickr 8.5 theme is a significant departure because it uses a new UI framework that is more Web 2.0-based. The new UI framework offers better server scalability and a smoother UI experience. Figure 3 shows the UI framework that enables Quickr 8.5 to work as a Web 2.0 application.
Figure 3. Quickr 8.5 theme as Web 2.0 application

Lotus Quickr 8.5 implements the Web 2.0 approach by means of the following: The page is widgetized. Updates occur on a portion of the page. The server provides data only; the client controls page composition and layout [Representational State Transfer (REST) calls]. Heavier use of dialogs (lightboxes) and single-page forms. Collects the information for the content in one place and sends it to the server to create/edit associated documents. Extensible by users. Components can be redefined and are swap-able. 5

Quickr 8.5 for Domino delivers a new default template and theme based on the new UI framework. There is no overlap between the 8.2 and 8.5 client code bases. The subsections below describe the framework in Quickr 8.5, which you need to understand before any starting any customization work.

3.1 Page layout

In Quickr 8.5, most pages have moved to the new framework, but there are still some pages that are actually remnants of the v8.2 UI; however, they are usually used only by place managers/owners and are not discussed in detail here. These v8.2 remnants are displayed inside an <iframe> of a lightbox, which includes: 1. 2. 3. 4. Members (note that every user must go there to access their profile). Folder Properties (note that in v8.5, authors and editors can create folders and access this). Customize the entire UI (Basics, Themes, Placebots, Forms, PlaceType options). Offline (supported in 8.5.0.1).

Figure 4 shows the Customize page, which appears inside a lightbox.

Figure 4. Customize page inside a lightbox

The other pages use the v8.5 UI framework. Figure 5 shows the Library page, which is based on 8.5 UI framework, and shows the widgets used in the whole page. From this figure, you can see that the whole page is widgetized.

Figure 5. The widgetized Library page

Table 3 describes step-by-step how a page is rendered under the Quickr 8.5 theme.
Table 3. Steps for rendering a page

Steps
1. The browser sends an http request. 2. The Quickr server handles the request and redirects it to access the .nsf database of the place automatically, if the myplace is found on the server. The Quickr server continues to handle the request and redirect it to access the first document in the toc view automatically. 3. The Quickr server processes the ?OpenDocument command, gets the value of the form field of the document (for example, h_PageUI), and then uses the form to render the document. 4. The Quickr server opens the form in HaikuCommonForms.ntf and resolves the tags in the forms. The server loads the skin element <QuickPlaceSkin> tag. After resolving the <QuickPlaceSkin> tag, the server sends the response to client.

Remarks
For example, http://www.quickr.ibm.com/LotusQ uickr/myplace

Server or client behavior?

For example, Server behavior http://www.quickr.ibm.com/myplac ehttp://www.quickr.ibm.com/Lotus Quickr/myplace/Main.nsf/h_Toc/4 df38292d748069d052567080016 7212/?OpenDocument

Server behavior

Server loads the skin layout (page.htm). This step is different from Quickr 8.2, which used many subforms and skin components that needed to be resolved by the server.

Server behavior

5. Client receives the response and executes the JavaScript, loading the related .js and css files. 6. Client initializes and renders the widgets. These widgets build up the whole page.

Loads the qwidgets.js, which contains widgets used in Quickr 8.5 theme. The layout of those widgets are defined in page.htm.

Client behavior

Some widgets will call Ajax to Client behavior retrieve data from the server side, plus there will be some interaction Server behavior (Makes response between those widgets. to these SOAP or Rest API requests).

Under the v8.5 theme the Lotus Quickr server provides data only through a Simple Object Access Protocol (SOAP) or REST API. The client side works as a consumer and retrieves data on demand. The page.htm is the main layout (v8.5 new theme) file and positions the main Quickr widgets, including Table of contents (TOC), Search, Main content (for library, calendar, etc.), footer, and so on. The default Quickr 8.5 theme relies heavily on JavaScript code to create and manipulate certain elements on the page. Quickr.js contains the important code to do this specifically for the Quickr 8.5 theme. Table 4 describes the main functions of these .js files. In the page.htm file, these functions are called one by one.
Table 4. .js files and functions

File
QuickrSupportUtil.loadServerBase()

Function
Loads the q_base form that provides server configurations to client side; for example, the information about the log-in user. Loads the core style sheet files. It loads the qstyles.css. Loads the core Dojo code. It loads /domjs/dojo1.3.2/dojo/dojo.js. Lotus Domino provides the /domjs Dojo . Loads the Dojo supplemental code needed by Quickr. It loads the //qphtml/skins/quickr/scripts/qdojo.js. Loads Quickr widgets code. It loads /qphtml/skins/quickr/scripts/qwidgets.js. Loads Sametime integration code. Performs some special initialization, for example, load some necessary JavaScript.

QuickrSupportUtil.loadCoreStyles() QuickrSupportUtil.loadCoreDojo()

QuickrSupportUtil.loadSupplementalDojo() QuickrSupportUtil.loadQuickrWidgets() QuickrSupportUtil.loadSTLink() QuickrSupportUtil.loadMainUI()

3.2 Widgets
Quickr 8.5 for Domino uses the Dojo Dijit framework to build and deliver its own widgets. A widget renders (that is, generates the markup for) a user interface (UI) component on the page, such as a name, a navigation control, or an entire folder view. It performs this activity on the client side and at creation time.

Widgets are analogous to the Quickr 8.2 skin components, but a skin component is generated on the server and sent to the browser as HTML or JavaScript. Some widgets will make asynchronous requests to the server to get data in XML or JavaScript Object Notation (JSON) format during rendering. Some widgets subscribe to events, often containing data that causes them to re-render. They can also publish events when triggered by a server response or user action. For example, Quickr 8.5 uses the quickr.widgets.view.toc widget to replace the TOC skin component (see table 5).
Table 5. Comparison of v8.2 skin components a nd v8.5 widgets Skin components in Quickr 8.2 Widgets in Quickr 8.5 <QuickPlaceSkinComponent name=TOC <div class="lotusInner" format={<li><Item></li>} selectedFormat={<li dojoType="quickr.widgets.view.toc"> class="lotusSelected"><Item></li>} </div> replaceString={Customize=&&Room Options=} prefixHTML={<div class="lotusMenu"><div class="lotusBottomCorner"><div class="lotusInner"><ul id="lotusTocEntryList">} postfixHTML={</ul></div></div></div>}>

Quickr widgets fall into four types based on rendering methods (for example, whether or not they use XSL) and on whether or not they use requests for data (see table 6).
Table 6. Widget types and their characteristics Widget type Requests data from server (feed)? Type 1 Type 2 Type 3 Type 4 No Yes No Yes Uses associated XSL to render itself? No No Yes Yes Examples Message Viewer What's New, Group Expander Link Page (creation) Library, Page, Member Picker, Person Card

All Quickr widgets are located in or under the domino\data\domino\html\qphtml\widgets directory. Figure 6 illustrates the structure of Quickr widgets. It is useful for you to understand the new framework when making your customizations.

Figure 6. Structure of Quickr widgets

Utility classes (not widgets), e.g., q_GeneralUtils, q_LocaleUtils Calendar widget code. Lists and ECM integration Menu widgets (context and drop-down). Dialog (Create folder dialog, Send notification dialog, etc). Page (Page, Upload, Imported, Link, etc.) and page field widgets Widget registry configuration. View (Library, Tabbed, Slide Show, etc.) and view control widgets. Base widgets for most Quickr widgets

Loads q_base data from server into q_BaseLoader object. Controller widget for all page content (pages and views).

Base model widget for requesting data from server. Controller widget for all popups and modal dialogs (lightboxes).

3.3 Widget registry

A Quickr 8.5 for Domino page is composed by means of widgets. The mechanism to deploy customized widgets into Quickr is important. Here we introduce the widget registry, with which mechanism you can deploy your widgets smoothly. The widget registry is located in <domino>\data\domino\html\qphtml\widgets\widgetRegistry.js. When this widget is first loaded, it will attempt to load the default configuration and the default extension files: <domino>\data\domino\html\qphtml\widgets\resources\widgetRegistryConfig.js <domino>\data\domino\html\qphtml\widgets\resources\widgetRegistryConfig_ext.js

These files contain the information used to determine which widgets to load for different conditions. For customization purposes, you can use widgetRegistryConfig_ext.js to register your extension widgets.

10

The config files have an array of objects named registerWidgets. Each object in the array has a type value, which can be one of these values: LOADEXTERNALSCRIPT REGISTERSTRINGS REGISTERMODULEPATH PAGE VIEW GLOBALREPLACE

LOADEXTERNALSCRIPT is used to load outside scripts, where: The only other value is fileName, which is the path to the file to be loaded. For the default theme, it loads the Quickr_ext.js file.

For example: { type: 'loadexternalscript', fileName: '/qphtml/skins/quickr/scripts/Quickr_ext.js' } REGISTERSTRINGS is used to load string resources for multi-locale support, where: id defines a unique name for this group of strings path is the location of the nls\<locale> directories for each locale. fileName is the name of the individual string-resource file names located in the nls\<locale>

For example: { type: 'registerstrings', id: 'quickr.system.strings', path: '/qphtml/skins/quickr', fileName: 'QuickrStrings.js' } REGISTERMODULEPATH is the Quickr wrapper for the dojo.registerModulePath function, where: name defines the name of the group of widgets path is the location of the widgets

For example: { type: 'RegisterModulePath', name: 'custom.widgets', path: '/qphtml/skins/custom/widgets' } 11

PAGE is used to define which widget to use when rendering a page, where: condition is evaluated to determine whether to use this widget: object defines the arguments passed into the ACTION.PAGE.OPEN event object also contains the field values of the document being opened, so the values in the fields of the opening document can determine which widget to use to render. Defined as object.entry.fields

useis the widget name to use this instead of quickr.widgets.page.defaultPage.

For example: { type: "page", condition: "(object.systemName=='h_WhatsNew')", use: "quickr.widgets.page.whatsNew" } VIEW is used to define which widget to use when rendering a view, where: condition is evaluated to determine to use this widget object defines the arguments passed into the ACTION.VIEW.OPEN event use is the widget name to use this, instead of quickr.widgets.view.defaultView

For example: { type: 'view', condition: "(object.systemName=='h_Calendar')", use: "quickr.widgets.view.calendar" } GLOBALREPLACE is used to replace one widget in the system with another, where: source is the original widget name use is the replacement widget name

This is useful for system-wide replacement of default widgets. Common candidates for replacement are: Rich Text Control Page Header Page About Section Breadcrumb TOC Footer

For example:

12

{ type: 'globalreplace', source: 'quickr.widgets.page.field.richText', use: 'sampleWidgetFolder.ckEditorExt' } Note that LOADEXTERNALSCRIPT, REGISTERSTRINGS, and REGISTERMODULEPATH are run when the config is loaded; there's no need for any additional code. Also, GLOBALREPLACE is run when the dojo.require function is called for the widget being replaced. PAGE and VIEW are run by the content controller when an ACTIONS.PAGE.OPEN or ACTIONS.VIEW.OPEN event is triggered. Figures 7, 8, and 9 show the relationship and flow of events between the Quickr widgets.
Figure 7. Customized Theme flow chart 1

13

Figure 8. Customized Theme flow chart 2

Figure 9. Relationship between widgets

TOC (Navigator)

Breadcrumb

State Tracker Widget Registry Utility Classes and Objects Baseloader AjaxUtils FolderUtils IconUtils LocaleUtils GenUtils XmlUtils NameUtils etc.

Page view widgets Page Upload Imported Link etc.

View widgets Library Tabbed Folder Slide Show Folder Index Tasks Calendar etc. Action bar widgets Folder Page Tasks Calendar Trash etc.

Content controller

Person Card Lightbox widgets Create Upload Create Imported File Create Folder Member Picker Send Link etc.

Pop-up controller

Menu widgets Folder Actions Page context Folder context Download etc. Place Actions

14

3.4 AJAX and XSL

The new theme in Quickr 8.5 for Domino employs a programming model that uses Asynchronous JavaScript + XML (Ajax) techniques, REST APIs, Web services, and Dojo widgets to achieve greater responsiveness and ease of use in most key areas. Whereas older themes made liberal use of the QuickPlace skin components to generate most of the page content on the server, the new theme in Quickr 8.5 uses widgets. These widgets make asynchronous requests to the server to get data in XML or JSON format during rendering. In Quickr 8.5, the widgets use the Dojo Ajax API to call the Web service: dojo.xhrGet( args ); dojo.xhrPost( args ); It also uses Extensible Stylesheet Language (XSL) technology, which can be considered as the style sheets for XML. In Quickr, the widgets will call a REST or SOAP API to retrieve data from the server side; most service responses are in XML format. Once a response is retrieved from the server as XML, the widget will apply the XSL transform and Dojo.parse of results to apply Quickr widgets to the special dom nodes. XSL is used for rendering the widget according to the returned XML-formatted response. Figure 10 shows the behavior of widgets using the XSL transform and Ajax.
Figure 10. Widget behavior using XSL transform and Ajax

Quickr Server
AJAX (SOAP, REST)

Response

Response (XML format, etc)

Widget A
apply to dom

XSL Transform
XSL

Widget B

Client side

15

Listing 1 shows some sample XSL code from Quickr.

Listing 1. Sample 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="IS_OFFLINE" select="''" /> <xsl:param name="TABLE_SUMMARY" select="''" /> <xsl:template match="/"> <div class="lotusFooter" id="lotusFooter"> <table cellspacing="0" width="100%" summary="{$TABLE_SUMMARY}"> <tr> <xsl:choose> <xsl:when test="$IS_OFFLINE = 'true'"></xsl:when> <xsl:otherwise> <th class="ConnectorSection"><div dojoType="quickr.widgets.misc.textlocalizer" key="FOOTER.CONNECTORS"></div></th> </xsl:otherwise> </xsl:choose> </tr>

3.5 Event model

Quickr uses the Dojo Toolkit to build the Web UI, especially the the Dojo publish/subscribe event model, which is available to customization developers. Dojo's publish and subscribe functions are conceptually an extension of the more familiar onclick and onload event handling, allowing registering functions as callbacks for arbitrary events. There are many events defined by Quickr, and you can extend these by defining your own. Figure 11 illustrates the event publish and subscribe in the Quickr 8.5 theme.

16

Figure 11. Event publish and subscribe

where the process is as follows: 1. 2. 3. 4. 5. 6. 7. User clicks on the Navigator Event is generated to open the folder Page Controller fields event. Loads handler widget for folder Widget opens folder and displays Widget generates event for current state Other widget (for example, the breadcrumb) updates display

In Quickr 8.5, there are two useful functions, publishEvent() and subscribeEvent(), which wrap the dojo publish() and subscribe() functions to keep track of which events have been subscribed to and to perform some sanitizing of events content as well. You should favor these methods over the built-in Dojo ones. Table 7 lists a few of the more commonly useful events published by Quickr. It is by no means an exhaustive list; many more events are defined in the quickr.widgets._event file, which you should review to learn more information about the events. You can also define your own event for customization. 17

Table 7. Some events published by Quickr 8.5

Event
ACTION.OPENLASTVIEWORPAGE

Description
This event is used to return the user to a particular view (such as a folder) after performing some action. The common example in Quickr is to return a user to the folder they were looking at after creating a new document. This event typically doesn't take an argument. This event is fired after the Quickr state has been updated by the user (for example if a folder has been created). It is useful to subscribe to this event in order to update the state of your customization whenever the underlying state has been changed by the user (although obviously if your widget needs to know about actions by other users, then this will probably not be sufficient). It typically doesn't make use of any arguments. These events are used to display informational messages to the user and are usually displayed above the document listing in a folder view. These events control the visibility of the loading icon that can be seen when the Web UI is performing a long-running operation. They do not take any parameters. These two events are called to open and close dialog windows in the Quickr UI. They wrap the dojo.Dialog class to provide this functionality.

ACTION.GENERAL.BASECHANGED

ACTION.MESSAGE.INFO ACTION.MESSAGE.ERROR ACTION.MESSAGE.CONFIRM ACTION.MESSAGE.WARNING ACTION.LOADING.SHOW ACTION.LOADING.HIDE ACTION.DIALOG.OPEN ACTION.DIALOG.CLOSE

3.6 Upgrade to use Dojo 1.3.2

Quickr 8.5 for Domino relies on Dojo version 1.3.2 that ships with Lotus Domino 8.5.1. If you want to upgrade your customization code on Quickr 8.5, you must pay attention to the changes in the Dojo API. The Dojo used by Quickr is located in Domino\data\domino\js\dojo-1.3.2. For more detailed information, refer to Section 6 of this paper.

3.7 Localized style sheets and string-resource files

Quickr 8.5 for Domino templates are multi-locale enabled. One server can display markup for multiple locales based on the browser's language setting. A user can choose the language through the browser setting. For example, if you choose German [de] as the first preferred language, then the Quickr interface will be shown with de. Figure 12 shows the Quickr for Domino interface in German.

18

Figure 12. Quickr UI in German

The Quickr 8.5 theme uses a a packaged CSS file called qstyles.css, which includes the theme-specific CSS definition and the oneui CSS definition. The oneui CSS is a number of style sheets that are common to Lotus Quickr as well as other to Lotus products with a "thin client" Web experience. For bidirectional (bidi) support, the Quickr 8.5 theme provides another style sheet, qstylesRTL.css, which is used when the preferred language is ar or he. Each locale has its own version of these files in a separate subdirectory under the nls directory, for example, en subdirectory for English, ar for Arabic, and so on. In the case of English, the themes style sheet, Quickr81.css, resides in the directory qphtml/skins/quickr/nls/en. Each of the subdirectories also contains a localized strings-resource file (QuickrStrings.js) in the format of JSON notation. NOTE: Currently Lotus Quickr 8.5 for Domino supports 28 languages: en, zh-tw, zh, fr, de, it, ja, ko, pt-br, es, ar, ca, da, nl, fi, el, he, no, pt, sv, th, tr, cs, hu, pl, ru, sk, sl. During your customization, you might need to add some new strings. You can: 1. 2. Collect the new strings and add them in JSON format into those string-resource files. Use REGISTERSTRINGS to load your JSON files in the widget registry (described in Section 3.3) so that you can use the new strings as follows:

19

To show in a Web page directly, you can add a widget of dojoType quickr.widgets.misc.textlocalizer. For example: <div dojoType="quickr.widgets.misc.textlocalizer" key="BANNER.PLACES"></div>

To add an attribute to a tag in the html (such as the "alt" attribute of an <img> tag), you would put this in the attribute: @@[JSONVARIABLE.NAME]@@. For example: <img src="/qphtml/skins/common/images/logo.gif" alt="@@[BANNER.LOGO_ALT]@@" class="lotusLogo"/>

To use it in JavaScript, you would call the following JavaScript function: q_LocaleUtils.getStringResource("JSONVARIABLE.NAME", "QuickrNext");

3.8 New qpconfig.xml settings pertaining to customization

Several new qpconfig.xml settings are available in Quickr 8.5 for Domino. Detailed descriptions about these settings are in the qpconfig.xml file itself. In this sub section we describe the new qpconfig items related to customization: <notifications>: Notifications control and templating; refer to qpconfig.xml for details. <themes restrict_choices="true allow_in_85_theme="false">: Theme-related settings. Only the default Quickr 8.5 theme and custom themes can be selected on the "Choose a Theme" page in Quickr 8.5 for Domino; all the other old themes are disabled. With this setting, however, you can enable the old themes (see table 8).
Table 8. Theme-related settings

Attribute
restrict_choices

Value
TRUE FALSE

Default

Description
Only "allowed" and custom themes can be selected on the "Choose a Theme" page.

yes

All themes may be selected on the "Choose a Theme" page. Make these settings apply even in 8.5-based themes.

allow_in_85_theme

TRUE FALSE yes

These settings do not apply in 8.5-based themes (only 8.5-based themes can be chosen).

<allowed>

Quoted comma-separated list of themes allowed if restrict_choices="true", specified by name. Valid standard theme names for this list (note that the current default Quickr theme is always allowed) are: "Quickr 8.0" "Quickr 8.0 (with classic navigation)" "Quickplace Classic" "Quickplace Classic 3.0" "Quickplace Organized" "Quickplace Simple" "Quickplace Clean Space" "Quickplace Shapes" "Quickplace Banner" "Quickplace Classic 1.0"

20

4 Creating a custom theme

Now we describe some methods of creating a custom theme based on the standard Quickr 8.5 theme, and we create a sample scenario that uses a custom theme. Well begin the sample scenario by giving the theme a different color scheme, using CSS and some custom images, and then re-branding the theme by changing the logo. After that, well make a significant change to the left-hand navigation area of the page, replacing one skin component and using some JavaScript techniques that you can reuse to make other modifications to your own custom theme. We also present a few variations on the approach described in the examples. NOTE: The sample theme described here (and available for download) is intended to serve as an example only. It might require further modifications and refinements for use in an actual production environment.

4.1 Getting started

To create a custom Quickr 8.5 theme, you must first create a place to apply the theme to. You can also use an existing place, but in any case you probably want to use this place as the basis for a template or PlaceType, so plan accordingly. Next, you must obtain the four files that youll upload to your place: stylesheet.css, page.htm, edit.htm, and listfolder.htm. These are located in the qphtml/skins/quickr directory in the servers file system. Although you might need to use someone with access to the Quickr servers file system to get the files, you should be able to get them simply by entering the URL of the file, for example: http://serverHostName/qphtml/skins/quickr/stylesheet.css http://serverHostName/qphtml/skins/quickr/page.htm The HTML files will, of course, appear as a relatively empty page in your browser. Just view the page source (right-click and select View Page Source in Mozilla Firefox or View Source in Microsoft Internet Explorer) and either save the page directly, or copy and paste the code into your text editor and save the file. In either case, make sure you save the file using the appropriate name (for example, page.htm). This process is faster if you just use the modified versions of these files available for download; however, it is more instructive to make these changes manually. The best and fastest approach is to copy and paste sections from the modified files into the standard Quickr 8.5 theme files obtained from your administrator. IMPORTANT: The edit.htm and listfolder.htm files are used for the 8.2 remnants, such as the Member and Customize pages. For most customizations, you won't need to customize these 8.2 remnant pages, so you can skip editing the edit.htm and listfolder.htm files if you wish.

4.2 Creating your theme

Now let's create the new theme from the four files. To do this, follow these steps (you must use Internet Explorer as your browser, since the theme files must be uploaded using an ActiveX control):

21

1. 2.

From most pages, you can select Customize Custom Themes. Click the green Create a Custom Theme button. Assuming you are using Internet Explorer, this takes you to the page to which you will upload your theme files (see figure 13).

Figure 13. Upload your theme files

3.

Upload your copy of stylesheet.css by either clicking the Browse button to find and select the file, or by dragging and dropping the file to the control (see figure 14).

22

Figure 14. Upload CSS file

4. 5.

Repeat the previous step for all three remaining HTML files (page.htm, edit.htm, and listfolder.htm). If you have a thumbnail image you wish to use for your theme, you can upload it using the appropriate control (see figure 15):

Figure 15. Upload a thumbnail image

Ideally, the image should occupy 80x60 pixels. You should now have a custom theme that is identical to the standard Quickr 8.5 theme. Before going on, test your theme by applying it to the place, as follows: 1. 2. Select Customize Choose a Theme. Select the theme you just created, for example, My Theme. (Note that, unless you uploaded a thumbnail image for the theme, only the name of the theme will appear here.)

Browse around your place to make sure everything looks as it should in the standard Quickr 8.5 theme. If all is well, lets now do some modifications to the theme.

Modification 1: Change the color scheme

In this example, we replace the blue color scheme with one sporting a reddish-brown look. To do this, we: 23

1.

Replace some gradient image files with another. These are 1-pixel-wide images that produce shaded backgrounds when repeated across an element, for example, as shown in figure 16.

Figure 16. Replace the background

2. 3.

Replace some image files with others. Change some hex color codes (for example, #CEE1FC) in the style sheet. Some of these are font colors, others background and border colors, and so on. Since qstyles.css contains many styles that you cant be without regardless of the customization you make one practical approach is simply to leave qstyles.css alone, and instead override existing style attributes, as appropriate, in an additional style sheet of your own. In this example, we only replace (override) styles and images that are part of the common, cross-product UI design, as opposed to the Quickr 8.5 theme design.

4.

Upload a custom folder into the <domino>\data\domino\html\qphtml\skin\ folder, in which we upload some images and the newtheme.css file (see figure 17).

Figure 17. Upload new CSS file

5.

Even though the file we upload here is not loaded by a Quickr 8.5-style theme by default, we can add a <link> tag in our theme's HTML files to force the file to be loaded after the standard Quickr 8.5 style sheets. So, we edit the page.htm file to add the following part in the header: <link rel="stylesheet" href="/qphtml/skins/custom/newtheme.css" type="text/css"/>

6.

After updating the page.htm, we need to upload the new page.htm onto the Quickr server following the previous steps. Now the newtheme.css can be used in the customized theme. 24

Now let's change the look and feel. First we want to change the page background, and weve copied a custom background.png file to the directory from which well be uploading our HTML files. We put just this one selector in newtheme.css: body.lotusui {background:#EFE6CC none repeat scroll 0 0;} Also, we can change the color of the title bar, using the following: .lotusTitleBar {background-color:#A61D21;border-bottom-color:#A61D21} .lotusTitleBar .lotusInner {backgroundimage:url(/qphtml/skins/custom/images/titlebarLeft.png);} .lotusTitleBar .lotusRightCorner {backgroundimage:url(/qphtml/skins/custom/images/titlebarRight.png);} .lotusTitleBar .lotusTabs li {background-color:#821413;border-color:#821413 #821413 #821413;} .lotusSpritesOn .lotusTitleBar {backgroundimage:url(/qphtml/skins/custom/images/titlebarLeft.png);} .lotusBanner ul.lotusLinks li.lotusSelected {background-color:#CFB275;}

Finally, we upload newtheme.css, clear the browser cache and refresh, and look at our place; it should now look like that shown in figure 18.
Figure 18. New CSS styles works

25

Modification 2: Change the branding

This step is simple; all we do is replace the Lotus Quickr brand logo with another image of our choice. The name of the standard logo file is logo.gif (see figure 19) located in qphtml/skins/common/images:
Figure 19. Standard Quickr logo

Although we could just replace that file with our own, in this example we make the change in the theme: 1. 2. Upload a new logo file into the <domino>\data\domino\html\qphtml\skin\custom folder; we can then use this image in .css definition. Edit the newtheme.css again, adding the following part:

.lotusLogo { background-image:url(/qphtml/skins/custom/images/logo.gif) !important; height:22px !important; width:116px !important; } 3. Then, upload newtheme.css, clear the browser cache and refresh, and look at our place; it should now look something like that in figure 20.

Figure 20. Logo changed

26

Now were ready to make a significant modification to the theme by making some more modifications to the HTML, plus some JavaScript programming.

Modification 3: Customizing TOC and adding Tip function

In our custom theme, the TOC component appears in the left-hand side of the page; now let's change it to right-hand side: 1. Edit the newtheme.css, adding the following style: .lotusColLeft{float:right} 2. Upload the newtheme.css, so the TOC will display in the right-hand side. Originally, the TOC appears as shown in figure 21.

Figure 21. Original TOC

Now let's change the look and feel of the TOC widget: 1. First, edit the newtheme.css to change the icon for each menu item:

.qtocsprite-qkrToc_h_Members, .qtocsprite-qkrToc_h_Home, .qtocsprite-qkrToc_h_Library, .qtocsprite-qkrToc_h_Library, .qtocsprite-qkrToc_h_49B9AB68350FB355482576890021FE8D, .qtocsprite-qkrToc_h_Calendar, .qtocsprite-qkrToc_h_TaskList, .qtocsprite-qkrToc_h_Index, .qtocsprite-qkrToc_h_TrashList{background-position:0px 0px;background-image:url("/qphtml/skins/custom/images/li_head_gray.gif")} The li_head_gray.gif is used as the icon of menu item in TOC. 2. Also we can do more modifications by adding the following style:

.lotusMenu, .portlet-menu{border:1px solid #E2E0E0;min-height:300px;backgroundcolor:#ffffff;-moz-border-radius-bottomleft:0px;-moz-border-radius-bottomright:0px;-mozborder-radius-topleft:0px;-moz-border-radius-topright:0px} .lotusMenu li{border-bottom:1px solid #E3E1E1} .qtocsprite{float:none} 27

.qlist li a{color:#000000} .qlist li a:hover{color:#999999;text-decoration:none;background-color:#FFF6C9} .qlist li.lotusSelected a, .qlist li.lotusSelected a:visited, .qlist li.lotusSelected a:active{background-color:#FDEA90;border-color:#E3E1E1;color:#000000 ! important;;background-image:url("/qphtml/skins/custom/images/li_head_red.gif")} 3. Upload newtheme.css, clear the browser cache and refresh, and look at our place; the new TOC appears as shown in figure 22.

Figure 22. New TOC

NOTE: In this case, we do not explain the style definition one-by-one. You can use Firebug or the IE development tool to check the elements in the page. TOC customization is done. Let's move on to implement a TIP function through JavaScript programming. 1. Write the customization code in QuickrCustom.js and upload it into the <domino>\data\domino\html\qphtml\skins\custom\scripts folder (see listing 2)

Listing 2. Customization code

function showTips() { var div = document.getElementById("lotusColLeft"); var divTips = document.createElement("div"); var h3 = document.createElement("h3"); var p = document.createElement("p");

28

divTips.id = "lotusColTips"; divTips.className = "lotusColTips"; h3.innerHTML = "Tips"; p.innerHTML = "This is a customized theme!"; div.appendChild(divTips); divTips.appendChild(h3); divTips.appendChild(p); } if (typeof(dojo) != "undefined") { dojo.addOnLoad(function(){ showTips(); }); } 2. After that, we need to load this JavaScript file in the page. So we edit the page.htm, adding the following part in the header: <script type="text/javascript" src="/qphtml/skins/custom/scripts/QuickrCustom.js"></script> 3. We upload the page.htm again and see something like that shown in figure 23.

Figure 23. Final customized theme

Were done! Feel free to modify and expand on what weve done in this example, or to use these methods to introduce other customization into your theme. 29

4.3 Creating a template (PlaceType) using your theme

If youve created a custom theme that you intend to use in more than one place, you will probably want to create a template (PlaceType) using that theme. The procedure for doing this has not changed materially from QuickPlace and Quickr 8.2, and is described in chapter 11, Creating PlaceTypes and a Turnkey Server of the IBM Redbooks publication, Customizing QuickPlace".

5 Customizing forms
The out-of-the-box forms are sufficient for many uses, but you can also create your own forms if needed.

5.1 Creating new forms

There are three ways to create forms: Create a simple form by using standard Quickr fields Import a Microsoft Office form Import an HTML form

The HTML form is the most useful form in Lotus Quickr. If you need more control over how your form appears in Quickr, or need to include JavaScript, then you should use an HTML form. The procedure for creating and uploading the forms has not changed and is described in Chapter 6, Forms in QuickPlace of the Customizing QuickPlace Redbooks publication. Section 6.4.2, Creating a poll within QuickPlace, provides a sample customized HTML form.

5.2 Migrating a v8.2 form to v8.5

This sample details how to migrate old forms to the 8.5 theme. This sample HTML Form is used for polling and has three modes for displaying pages: Design mode. The poll is set up. The author fills in the required fields and submits the poll. Polling mode. The author casts a vote as shown. By doing this, he or she modifies the page on which the poll is based. When the vote is cast, a cookie is set on the authors machine. Polling result mode. The page is displayed in this mode when the cookie has been set on the authors machine. The cookie will expire after a preset date, which will enable the member to take part in the poll again.

NOTE: Here we take this polling form, for example, to explain what needs to change during the migration. The changes will be highlighted. We separate the codes of the poll HTML form by function and explain the changes on each part.

5.2.1 Fields in the form

First we need to add some customized fields in the form, as compared in table 9.

30

Table 9. Customized fields Polling form in 8.2 theme <html> <head> <title>Poll</title> </head> <body> <input type=hidden name=h_Name> <!-- Flag to show whether the poll has been designed --> <input type=hidden name=c_IsDesigningPoll> <!-- The choices entered --> <input type=hidden name=c_PollChoices> <!-- Results of the poll --> <input type=hidden name=c_VoteTally> <!-- Information about the poll --> <input type=hidden name=c_pollInformation> <!-- Temp value of h_Authors --> <input type=hidden name=h_Authors value=*/*/*/*> <!-- For the poll to always use the Page skin --> <input type=hidden name=h_SkinTypeOverride value=h_Page>

Polling form in 8.5 theme <html> <head> <title>Poll</title> </head> <body> <input type=hidden name=h_Name> <!-- Flag to show whether the poll has been designed --> <input type=hidden name=c_IsDesigningPoll> <!-- The choices entered --> <input type=hidden name=c_PollChoices> <!-- Results of the poll --> <input type=hidden name=c_VoteTally> <!-- Information about the poll --> <input type=hidden name=c_pollInformation>

Changes. Compared with the old polling form, we removed two fields that are not needed. In the 8.5 theme, we use a page ACL common component, so h_Authors is no longer necessary. In the 8.5 theme, we always use h_page skin, so h_SkinTypeOverride is also not needed. The other fields need no changes. The fields listed in table 10 are hidden in the poll page.
Table 10. Fields hidden in poll page Field Name h_name c_IsDesigningPoll c_PollChoices c_VoteTally c_PollInformation Description The name of the poll is set in the system field h_name. This field is set when the poll is created. The user-defined field is used to check whether the form is being designed. This user-defined field stores the poll choices. The results of the vote are stored in this user-defined field. This user-defined field stores descriptive information about the poll. This is entered on creation of the poll.

31

5.2.2 Functions to check mode

To check for the edit and vote-casting mode, Quickr 8.5 for Domino provides the JavaScript variable h_isBeingEdited, which we can use directly (see table 11).
Table 11. New and old implementations Old implementation function IsEditing( ) { return !(location.href.indexOf ('EditDocument') == -1); } function IsDesigning( ) { return (typeof (c_IsDesigningPoll) != "undefined" && c_IsDesigningPoll == ''); } New implementation function IsEditing( ) { return h_isBeingEdited; } function IsDesigning( ) { return (typeof (c_IsDesigningPoll) != "undefined" && c_IsDesigningPoll == ''); }

5.2.3 Design mode

If IsDesigning() returns true, the options for creating a poll will be displayed (see listing 3). Related codes can remain unchanged.
Listing 3. IsDesigning() code if ( IsDesigning( )) { // we are in edit mode - let's show the options for the vote document.write ('Please enter the <b>subject</b> of the poll:'); document.write ('<br><' + 'input name=c_PollName>'); document.write ('<br><br>'); document.write ('Information about the poll:<br>'); document.write ('<' + 'textarea name=c_pollInformation cols=40 rows=5></textarea>'); document.write ('<br><br>'); document.write ('What choices do you want users to vote on [one choice per line]:<br>'); document.write ('<' + 'textarea name=c_scratchPollChoices cols=40 rows=10 wrap=off></textarea>'); document.write ('<br><br>'); }

5.2.4 Polling mode

The polling mode lets users who have not voted offer the vote (see table 12).
Table 12. Comparison of polling mode codes Codes about polling mode in 8.2 theme // if the current user has not voted // offer the vote if ( !HasCookie( )) { var HTML = ""; HTML += '<br><span class=h-pagetitle-text>'; HTML += h_Name; HTML += '</span><br>'; HTML += c_pollInformation + '<br><br>'; HTML += '<' + 'input type=hidden name=c_VoteTally value="'; if (typeof ( c_VoteTally) != "undefined"){

Codes about polling mode in 8.5 theme // if the current user has not voted // offer the vote if ( ! window.q_CookieUtils.hasCookie(h_PageUnid + "_vote") ) { var HTML = ""; HTML += '<br><form name="voteform" id="voteform" method="post"><span class=h-pagetitle-text>'; HTML += h_Name; HTML += '</span><br>'; HTML += c_pollInformation + '<br><br>;

32

HTML += c_VoteTally; } HTML += '">'; document.write( HTML); var pollchoices = c_PollChoices.split(","); for (var i = 0; i < pollchoices.length; i++) { document.write ('<' + 'INPUT TYPE=radio NAME=c_CurrentChoice VALUE="' + i + '">' + pollchoices[i] + "<p>"); document.write('<input type="button" value="Submit" class="h-pageSmall-text" onClick="javascript:MyVoteSubmit( )">'); }

HTML += '<' + 'input type=hidden name=c_VoteTally value="'; if (typeof ( c_VoteTally) != "undefined"){ HTML += c_VoteTally; } HTML += '">'; var pollchoices = c_PollChoices.split(","); for (var i = 0; i < pollchoices.length; i++) { document.write ('<' + 'INPUT TYPE=radio NAME=c_CurrentChoice VALUE="' + i + '">' + pollchoices[i] + "<p>"); HTML += '<input type="button" value="Submit" class="h-pageSmall-text" onClick="javascript:MyVoteSubmit( )"></form>'; document.write( HTML); }

Changes. We needed to migrate to use functions provided in the 8.5 theme. In this example, we use q_CookieUtils.hasCookie().

5.2.2 Polling result mode

The third mode displays the results of the poll (see listing 4); related codes remain unchanged.
Listing 4. Sample polling result code else { // write out the results of the poll document.write ('<table width="100%" border="0"><tr><td class=h-pagetitle-text>' + h_Name + '</td></tr></table>'); document.write( c_pollInformation + '<br><br>'); document.write ('Here are the results of the poll so far:<br><br><hr>'); var pollData = new Array( ); var total = 0; for (var i = 0; i < pollOutput.length; i+=2) { pollData[pollData.length] = new Object( ); pollData[pollData.length-1].text = pollOutput[i]; pollData[pollData.length-1].count = parseInt( pollOutput[i+1]); total += pollData[pollData.length-1].count; } var tmp = ""; for ( i=0; i < pollData.length; i++) { tmp += pollData[i].text; tmp += "<br>"; if (total) { tmp += Math.round(pollData[i].count/total*100); } else { tmp += "0"; } tmp += "% " + "("+ pollData[i].count + ")"+"<p>"; } document.write(tmp); document.write( "<br>Total Votes: " + total + "<br>");

} }

33

5.2.6 Polling submit function

The polling submit function must update the c_VoteTally field value for the document, after which we need to set the cookie to prevent the author from voting again, as defined at the beginning of the script (see table 13).
Table 13. Comparison of polling submit functions Polling submit function in 8.2 theme Polling submit function in 8.5 theme function MyVoteSubmit( ) { SaveVote(G_CurrentForm); G_CurrentForm.h_SetEditCurrentScene.value = 'h_StdPageEdit'; G_CurrentForm.submit( ); } function SaveVote( myForm) { var i, j; // unpack the vote data var localvoteTally = new Array(); var pollchoices = c_VoteTally.split(","); for (i = 0, j = 0; i < pollchoices.length; j++, i+=2) { localvoteTally[j] = parseInt(pollchoices[i+1]); } var selectedValue = getRadioValue( myForm.c_CurrentChoice); if ( typeof (selectedValue) != "undefined") localvoteTally[selectedValue]++; // pack it back into the field myForm.c_VoteTally.value = ""; for (i = 0, j = 0; i < pollchoices.length; i+=2, j++) { myForm.c_VoteTally.value += pollchoices[i] + "," + localvoteTally[j]; if ((i + 2) < pollchoices.length) myForm.c_VoteTally.value += ","; } function MyVoteSubmit( ) { SaveVote(); } function SaveVote() { var myForm = dojo.byId("voteform"); var i, j; // unpack the vote data var localvoteTally = new Array(); var pollchoices = c_VoteTally.split(","); for (i = 0, j = 0; i < pollchoices.length; j++, i+=2) { localvoteTally[j] = parseInt(pollchoices[i+1]); } var selectedValue = getRadioValue( myForm.c_CurrentChoice); if ( typeof (selectedValue) != "undefined") localvoteTally[selectedValue]++; // pack it back into the field myForm.c_VoteTally.value = ""; for (i = 0, j = 0; i < pollchoices.length; i+=2, j++) { myForm.c_VoteTally.value += pollchoices[i] + "," + localvoteTally[j]; if ((i + 2) < pollchoices.length) myForm.c_VoteTally.value += ","; } var unid = window.q_GeneralUtils.getParameterFromUrl(" unid"); var xml ='<snx:field name="c_VoteTally" fid="c_VoteTally" pstId="[@P'+window.q_GeneralUtils.getPlaceNa me() +'/@R'+window.q_GeneralUtils.getRoomNSF() +'/@D'+unid+']" type="string">' + myForm.c_VoteTally.value +'</snx:field>'; window.q_DocFolderUtils.submitWithXmlRest( "",unid,xml, function() { // save the cookie window.q_CookieUtils.setCookie(h_PageUnid + "_vote","1"); alert("vote successfully!"); window.location.reload(); });

34

Changes. In the 8.5 theme, the UI framework uses an Ajax mechanism and consumes Web services in most scenarios. So we must call functions to send a REST request to update the document, and we also need to use the new q_CookieUtils.setCookie function to set the cookie.

5.2.7 Polling design submit function

The script in listing 5 completes the save of the form in design mode, checking if more that one choice was entered during edit mode. No changes are needed.
Listing 5. Script to save form function SaveDesignModeParams(myForm) { // read the choices var pollchoices = myForm.c_scratchPollChoices.value.split('\n'); if ( pollchoices.length < 2) { alert ("you must enter more than one option"); return false;

}
myForm.h_Name.value = myForm.c_PollName.value; myForm.c_PollChoices.value = pollchoices.join(","); pollchoices = myForm.c_scratchPollChoices.value.split('\n'); myForm.c_VoteTally.value = ""; for (var i = 0; i < pollchoices.length; i++) { myForm.c_VoteTally.value += pollchoices[i] + ",0"; if (i < pollchoices.length-1) myForm.c_VoteTally.value += ","; } myForm.c_IsDesigningPoll.value = '0'; return true;

function QDK_HTMLForm_OnSubmitHandlerCallback( theForm ) { if ( IsDesigning( )) { return SaveDesignModeParams( theForm); } }

In this part, we use two Quickr-specific JavaScript functions existing in Lotus Quickr. They are event handlers that can be called when the form is loaded from Lotus Quickr, or when a page created by the form is submitted to Quickr. This JavaScript function is called when the form is loaded from Lotus Quickr. It can, for example, set certain default field values: QDK_HTML_FormOnLoadHandlerCallback (theForm) This JavaScript function is also called when the form is loaded from Lotus Quickr. It can, for example, check if the user has entered data into fields that must be filled. QDK_HTML_FormOnSubmitHandlerCallback (theForm) After we make these changes to the polling form, the form can be used under the 8.5 theme.

5.2.8 Summary of HTML form migration

From the sample, you can see that the basic mechanism is not changed. You can add your 35

special fields and construct the UI by JavaScript as desired, and you can hook the QDK_HTML_FormOnLoadHandlerCallback and QDK_HTML_FormOnSubmitHandlerCallback events. The necessary changes are focused on the JavaScript variables and API provided by Lotus Quickr and also by the Dojo API. For more details, refer to Section 8. Figures 24, 25, and 26 show the migration results.
Figure 24. Create New Voting

36

Figure 25. Attend the voting

37

Figure 26. View the voting result

6 Customizing widgets
This chapter introduces some typical customization samples for widgets, using customized widgets, xsl, and the widget registry. Here we just briefly introduce those samples. For the detailed implementation, refer to the wiki article, Quickr 8.5 Theme Customization: list of related Wiki articles.

6.1 Sample custom themes for Quickr 8.5 for Domino

This is a custom theme sample, and figure 27 is a snapshot of this custom theme. Refer to the Sample Custom Themes for Quickr Domino 8.5 wiki article for the detailed implementation and codes.

38

Figure 27. Sample custom theme

6.2 Changing footer links

This sample customizes the footer links in pages, using global replace in the widget registry to replace the original footer widget with a new customized footer widget. Figure 28 shows the new footer links in Quickr places. Refer to the Sample Custom Themes for Quickr Domino 8.5 wiki article for the detailed implementation and codes.
Figure 28. New footer shown in Lotus Quickr

6.3 Switching from CKEditor to other rich text editors

As shown in figure 29, Quickr 8.5 integrates the CKEditor for rich text editing. Refer to the Product Documentation topic, Editing the footer links in a Quickr Domino Place, for more details.

39

Figure 29. CKEditor in Lotus Quickr

This sample uses global replace to switch the CKEditor for the Dojo Editor in Quickr 8.5. A similar solution can be used to change from CKEditor to other editors. Figure 30 shows the customization result. For detailed implementation, refer to the wiki document, Switching the CKEditor for other editors.
Figure 30. Dojo Editor in Lotus Quickr

6.4 Customizing Action buttons

This sample shows how to add Action buttons to, and remove existing Action buttons from, the folders view. The added Action buttons will display to the right-hand side of the "More Actions" button in the folders view. Figure 31 shows the customization result of this sample. For more details refer to the wiki article, Creating an Action Button in Folders View.

40

Figure 31. Creating Action button in folders view

6.5 Customizing menu items

This sample shows how to add, remove, or disable menu items or submenu items. Figure 32 shows the customization result. For the detailed implementation, refer to the wiki article, Menu items customization.
Figure 32. Menu items customization

6.6 Adding a slideshow view

This sample customizes the page widget to view image attachments. The slideshow is used when the number of images attached to a page is greater than one. For those pages with only one image attachment, the image will be displayed directly. Figure 33 shows how a page with single and multiple attachments is displayed. For the detailed implementation, refer to the wiki article, Adding a slideshow view to a page.

41

Figure 33. Single attachment and slide show

42

6.7 Inline attachments

This sample shows how to display PDFs and Flash movies directly within Quickr. The sample overrides the Quickr page view behavior so as to load the custom widget when rendering the content of a page. Figures 34, 35, and 36 show the results of this customization. For more details, refer to the wiki article, Inline Attachments: Displaying PDFs, images and Flash files directly within Quickr.
Figure 34. PDF attachment

Figure 35. Picture attachment

43

Figure 36. Flash attachment

6.8 Adding a Java applet for uploading files to a place

This sample embeds a Java applet to upload files to the Library. The applet was present in Quickr 8.2 but was then removed in Quickr 8.5. The sample adds it back to achieve the dragand-drop user experience. Figure 37 shows the customization result. For more details, refer to the wiki article, Adding a Java applet for uploading files to a place.
Figure 37. Adding a Java applet for uploading files to a place

44

6.9 Embedding an XPages Notes database into a Quickr for Domino place
This sample shows an embedded XPage database in an iframe within a page, in which we: 1. 2. 3. 4. Create the widget file that is needed. Extend the widget registry. Subclass the defaultPage.js to add in new functionality. Create a form to store the URL.

For more details, refer to the wiki article, Embedding an XPages Notes Database into a Quickr Domino Place.

6.10 Tag cloud

When creating new pages we might want to add tagging to the page and then display these tags on-screen with links to the tagged pages. Figures 38 and 39 show the result of this Tag cloud customization. For more details, refer to the wiki article, Adding tags to IBM Lotus Quickr for Domino 8.5.
Figure 38. Tagging box

45

Figure 39. Tag view

6.11 Using the Quickr event system

Starting with version 8.5, Lotus Quickr uses the Dojo Toolkit to build the Web UI. The Dojo publish/subscribe event model is extensively used by Quickr and is also available to customization developers. This sample explains how to use the Quickr event system. For more details, refer to the wiki article, Using the Quickr Event System.

6.12 Delivering Quickr 8.5 customization widgets via templates

Quickr Templates provide a convenient way to deliver and re-use place extensions. Prior to Quickr 8.5, these customizations consisted of simple theme-layout and styling changes (via page.htm, edit.htm, etc.), skin changes, and database schema elements (custom forms, etc.). In Quickr 8.5 there's a new way to deliver customization; that is, by extending the rich browser framework of Quickr Dojo dijits. For more details, refer to the wiki article, Delivering Quickr 8.5 theme customizations via template.

7 Migrating customized templates to the 8.5 theme

Since the default theme in Quickr 8.5 for Domino is based on the new UI framework (widgets and service), migrating legacy customized templates to the 8.5 theme requires a special effort. In this section, we provide some guidance and tips for the migration. There are many customized 8.2 templates that have been developed by Quickr customers and Business Partners. Customization might touch the following areas: htmls (theme related), JavaScripts, CSS, customized forms and fields (Quickr), document, agents, and .dlls. During the migration, most issues occur in JavaScripts and codes in customized forms. Here we attempt to enumerate some potential issues when migrating these codes. Additionally, we introduce how to migrate your customized theme and CSS to the 8.5 framework. 46

7.1 Migrating htmls and CSS (theme related)

Typically we touch theme-related htmls for theme customization. Table 14 shows the differences between the 8.2 theme and the 8.5 theme with respect to the theme-related htmls.
Table 14. Differences between theme-related htmls 8.2 theme 8.5 theme page.htm (skincomponents, scenes) edit.htm (skincomponents, scenes) listfolder.htm (skincomponents, scenes) slideshow.htm (skincomponents, scenes) headlines.htm (skincomponents, scenes) page.htm (widgets) edit.htm (skincomponents, scenes, 8.2 remnants) listfolder.htm (skincomponents, scenes, 8.2 remnants)

For the theme migration, we need to: 1. 2. Remove slideshow.htm and headlines.htm. Migrate edit.htm and listfolder.htm based on the 8.5 theme. The skincomponents and scenes mechanism are still used and are not much different from 8.2, but these html files are used only for Members, Folder Properties, Customize, and Offline pages. When these pages are shown in a dialog box, only the main contents are shown; the page header, page bottom, and TOC are hidden. So you should consider whether you need to customize these pages. 3. Migrate page.htm. In Quickr 8.5, page.htm is the main layout for most pages. There is no scene; both open a document and edit a document use page.htm. The new page.htm uses widgets, so you must use widgets instead of skincomponents, and you can find the corresponding widget to replace the skincomponents you used. In page.htm, you can also use your customized widgets.

Quickr 8.5 uses IBM Lotus One UI V2 CSS. The domino\data\domino\html\qphtml\skins\quickr\themes\qstyles.css style sheet is loaded by default. Your previously customized CSS definition might not work as expected, so you should include your own CSS file to override some default CSS definition. Beyond CSS, if you need to customize the look and feel of the existing Quickr widgets, you can try editing the XSL files used to define the UI of widgets. For example, toc.xsl is used by the TOC widget. These XSL files are located in domino\data\domino\html\qphtml\widgets.

7.2 Migrating JavaScripts and customized forms

Since the 8.5 theme is based on a totally new UI framework, you might encounter several kinds of issues when migrating your customized codes and forms. The following are some potential issues and a solution for each of them:

Missing JavaScript variable

In the 8.2 theme, there are many JavaScript variables initialized during page loading. These variables provide much information, such as field values of the current document, server configurations, log-in user information, and so on.

47

Some customization code will use these JavaScript variables. However, some of the JavaScript variables are not available in the 8.5 theme, so for those missing variables, you need to change them to use new JavaScript variables. The following sample JavaScript variables are for server configuration: var QuickrCGIVariables Var G_CacheCompliantUrlTemplate window.q_BaseLoader.environment.cgiVariables window.q_BaseLoader.environment.cacheCompliant UrlTemplate

The following sample JavaScript variables are for log-in user configuration: haiku.loginName = 'Qphotos'; haiku.userName = 'Qphotos'; var currentUserAccess = 6; window.q_BaseLoader.user.loginName window.q_BaseLoader.user.userName window.q_BaseLoader.user.access

IMPORTANT: The JavaScript variables for fields of the current document and some other common JavaScript variables are still available in HTML forms. The 8.5 UI framework continues to support these JavaScript variables, and you can still use them in your customized HTML forms. The following variables are still available: * (fields JS variable, for example, h_Authors) fieldNames.* (fields, for example, fieldNames.h_Authors) h_isBeingEdited h_PageUnid isAuthor h_IsNewDoc h_ClientBrowser h_protocolAndServer h_serverRootPath getProtocalAndServerUrl getAbsoluteServerRootPath h_DocCreated

For JavaScript variables not mentioned above, you might need to change them. The window.q_BaseLoader variable contains much useful information, so if you encounter some issues with variables missing, check this variable first. The h_BuildNumber variable, which provides the version of Quickr for Domino, has no variable to replace it since version information is not provided to the client in Quickr 8.5 for Domino.

API changes around Dojo and Quickr

Quickr 8.5 for Domino relies on Dojo 1.3.2 that ships with Domino 8.5.1. If you want to upgrade your customization code on Quickr 8.5, you must be aware of changes in the Dojo API. For example, any customization that uses the Dojo function, dojo.io.bind, in its code to make an AJAX call will not work because Quickr 8.5 uses a newer version of the Dojo libraries (1.3.2) 48

than the version previously used in Quickr 8.2 (dojo 0.4). Dojo.io.bind is not available in Dojo 1.3, so any customized code that calls this function will fail. The solution is to change your Dojo dojo.io.bind calls to dojo.xhrGet \ dojo.xhrPost. Table 15 shows the AJAX API changes. Again, be aware of the parameters of this new API.
Table 15. Ajax API changes Dojo 0.4 Ajax API var ajaxArgs = { url: sURL, mimetype: "text", method: theMethod, preventCache : thePreventCache, error: function(type, errObj){ }, load: function(type, response, evt) { eval(sResponseHandler + "(response" + sPassedParms + ")"); } }; dojo.io.bind(ajaxArgs); Dojo 1.3.2 Ajax API var xhrArgs = { url: sURL , handleAs: "text", preventCache: true, load: function(data, ioargs) { targetNode.innerHTML = "XHR returned HTTP status: " + ioargs.xhr.status; }, error: function(error, ioargs) {; } } //Call the asynchronous xhrGet var deferred = dojo.xhrGet(xhrArgs);

Another example is dojo.date.format; in Dojo 1.3.2, you must use dojo.date.locale.format instead. Also, the Dojo event connection is changed: dojo.event.connect()/disconnect() --> dojo.connect()/disconnect(). The dojo.lang was removed, so you need to use comparable dojo.* apis; for example, use dojo.forEach() to replace dojo.lang.forEach() for array iteration. If your customization code uses a Dojo widget that is not available in Dojo 1.3.2, then you need to use the new widget. For example, use: dijit.form.ComboBox to replace dojo.widget.ComboBox dijit.Tooltip to replace dojo.widget.Tooltip

The dojo.widget.createWidget() method is not available for creating widgets. You need to use a new widget and apply it to the DOM node. For example: Var categoriesField = dojo.byId("categoriesField") var categoriesCombo = new dijit.form.ComboBox( { name:"categories", autocomplete:true}, categoriesField); And you can also use some Quickr widgets. The following are some JavaScript files that are not used in the 8.5 theme:

49

/qphtml/html/common/qp_common_code.js; /qphtml/skins/common/scripts/QuickrCommon.js; /qphtml/html/common/qp_versions.js; /qphtml/html/common/dynamic_toc.js; /qphtml/html/common/qp_write_html.js; /qphtml/html/common/ComplexExpression.js;

If your 8.2 customization used some functions in these files or extended these files, then you'll need to remove or migrate them. Some code in Quickr subforms and forms is also not available, so you also need to migrate them. For example, if you use QuickrXMLUtil, which is defined in qp_common_code.js, you can move to use window.q_XmlUtils in the 8.5 theme. The Quickr framework provides many special utilities that you can try using in your customization code. Table 16 lists some of these common utilities and their usage. For more details, check their JavaScript codes located in: Domino\data\domino\html\qphtml\widgets\common
Table 16. Common utilities Utility window.q_GeneralUtils window.q_BaseLoader window.q_AjaxUtils window.q_CookieUtils window.q_DateUtils window.q_DocFolderUtils Description Provides some common functions, such as JSON parse, get URL parameters, etc. Provides lots of server configuration and log-in user information. Encapsulates Dojo Ajax API and integrates with Quickr authentication mechanism. Cookie-related functions. Encapsulates Dojo Date API; used for date convert and format. Encapsulates common APIs for operations on a doc while in a folder view; provides some common functions such as remove, rename, move. Encapsulates common APIs for handle document, such as retrieve document entry information. Encapsulates common APIs for handle folder, such as create folder, retrieve folder ACL information. Utilities to handle multi-locale issues. Utilities to send Rest request; easy to build up a Rest request. Utilities to handle .xml data; provides common functions for parsed data from response of Web service.

window.q_DocUtils window.q_FolderUtils window.q_LocaleUtils window.q_RestUtils window.q_XmlUtils

JavaScript hook and event

A customization might hook some JavaScript functions, but these hooks might not work because the hooked functions are not available. Listing 6 shows how to customize the context menu in the 8.2 theme.

50

Listing 6. Customizing the context menu

dojo.addOnLoad(function(){ window.QP_ContextMenu_write_contextmenu = window.QP_ContextMenu_write; window.QP_ContextMenu_write = function() { // add the customized code var menu = this; menu.addSeparator(); menu.addItem( Quickr_ContextMenuUtil.resources.QUICKR_HOMEPAGE, "http://www-01.ibm.com/software/lotus/products/quickr/", "_blank" ); window.QP_ContextMenu_write_contextmenu.apply(menu, arguments); }; }) Note that QP_ContextMenu_write is not available in Quickr 8.5, so you need to change it. For this example, the solution is to implement a widget to extend the menu based on the 8.5 theme. Refer to the wiki article, Menu items customization topic, for an example of this. Fortunately there are some JavaScript hooks still available, such as QDK_HTMLForm_OnSubmitHandlerCallback and QDK_HTMLForm_OnLoadHandlerCallback, that you can implement in your forms: QDK_HTMLForm_OnLoadHandlerCallback is invoked when the page is loading QDK_HTMLForm_OnSubmitHandlerCallback is invoked when a user starts to submit the form; for example:

function QDK_HTMLForm_OnSubmitHandlerCallback(theForm){ // my function to check the field in the form. If return false, the form won't be submitted. return checkFields(theForm); } Besides the JavaScript hook, you can use the event mechanism in the 8.5 theme to subscribe or publish the event. The following sample shows a notification during the page loading: function QDK_HTMLForm_OnLoadHandlerCallback(theForm){ var _event_widget = new quickr.widgets._event(); _event_widget.publishEvent( _event_widget.ACTION.MESSAGE.INFO, {message: "Thank you, you are using my customized form!"} ); } Figure 40 shows the effect of the notification message.

51

Figure 40. Notification message

In the customization code, you might have your own menu or link, for example, to put a Create new document link in the page. For the link or menu, you must follow the event mechanism of the 8.5 theme. Table 17 shows a comparison of the old and new Create a document links.
Table 17. Create a document link comparison Old implementation var sUrl = "../../h_Index/$new/?EditDocument&Form=h_PageUI"; (Construct the URL sUrl += "&PreSetFields=h_EditAction;h_New,h_SetReadScene;h_StdPageRead,h_SetEdi yourself) tScene;h_StdPageEdit"; sUrl += ",h_ReturnToPage;" + h_PageUnid; sUrl += ",h_Form;" + formUNID + ",h_SetCommand;h_PreProcessForm"; var vf_nonceToken = vf_getCookie("NonceToken"); if(vf_nonceToken){ sUrl += ',h_Nonce;' + vf_nonceToken; } location.href = sUrl; New implementation (Construct the URL through event, and you can also use the event publish mechanism) var _event_widget = new quickr.widgets._event(); var oEvt = new quickr.widgets.misc.eventlink( { event: _event_widget.ACTION.PAGE.CREATE, args: {folderUnid: "CE6A3D6B1F546C9405256708001671FF", formUnid: formUNID} } ); window.location.href = oEvt.getEventLinkFromProperties(oEvt.getLinkArguments()); oEvt.destroyRecursive();

Conversion matrix
Table 18 is the JavaScript API conversion matrix for the most common APIs. 52

Table 18. Conversion matrix

From:
dojo.io.bind dojo.date.format dojo.event.connect()/dojo.event.disconnect() dojo.lang.* dojo.widget.ComboBox dojo.widget.Tooltip dojo.widget.createWidget

To:
dojo.xhrGet \ dojo.xhrPost dojo.date.locale.format dojo.connect()/dojo.disconnect() dojo.* (try to find the comparable here, for example, dojo.forEach() to replace dojo.lang.forEach()) dijit.form.ComboBox dijit.Tooltip new the widget directly For example: new dijit.form.ComboBox({}, categoriesField); window.q_XmlUtils.*, For example, replace QuickrXMLUtil.getNodeValuesByTagName() with window.q_XmlUtils.getDocTagValue() window.q_LocaleUtils.*, For example, replace QuickrLocaleUtil.getStringResource() with window.q_LocaleUtils.getStringResource

QuickrXMLUtil.*

QuickrLocaleUtil.*

QuickrGeneralUtil.*

window.q_GeneralUtils.* For example, replace QuickrGeneralUtil.getDownloadLink() with window.q_GeneralUtils.getDownloadLink() window.q_DateUtils.* For example, replace QuickrDateUtil.convertDateTo8601String() with window.q_DateUtils.convertDateToISO8601String() window.q_CookieUtils.* For example, replace QuickrCookieUtil.getCookie() with window.q_CookieUtils.getCookie() window.q_AjaxUtils.post window.q_AjaxUtils.get window.q_AjaxUtils.postMultipartForm

QuickrDateUtil.*

QuickrCookieUtil.*

QPAjax_Request QPAjax_SubmitForm

7.3 Using 8.2 unchanged customizations on an 8.5 server

It's possible that the effort to migrate existing customized 8.2 templates or places to the 8.5 theme might be too much to take on. In that case, you can choose to continue using the 8.2 theme for them, so that no changes will be needed for your customization work. 53

When upgrading your Quickr 8.2 server to 8.5, if the load qptool upgrade -f command is used to upgrade your places, then all places with a default theme will be upgraded to the 8.5 theme. If the "-f" argument is not used, then all 8.2 places will continue to use the 8.2 theme. For those places that already have been changed to use the 8.5 theme, you can also restore them to the 8.2 theme by adding the following entry in the qpconfig.xml file: <themes restrict_choices="true" allow_in_85_theme="true"> <allowed>"Quickr 8.2","Quickr 8.0", "Quickr 8.0 (with classic navigation)","Quickplace Classic","Quickplace Simple"</allowed> </themes> Then you'll be able to customize and switch your places back to the 8.2 theme.

8 Quickr for Domino hooks

Quickr 8.5 for Domino provides APIs to intercept and handle certain events on the server side and provides hooks to JavaScript function calls on the client side, allowing you to log or modify certain default operations of Lotus Quickr.

8.1 Server event hook

There are two ways of creating server hooks for Lotus Quickr: C/C++ Placebots (Domino agents)

For more details, refer to the wiki article, Preview: Customizing Lotus Quickr Services for Domino 8.2 with the Event interface.

8.2 JavaScript hook

Quickr 8.5 for Domino provides the JavaScript hook function. Here we explain the JavaScript hook in the 8.5 theme and 8.2 theme, using two files: Quickr_ext.js, which is used for the 8.5 theme Quickr85_ext.js, which is used for 8.2 theme

For other themes, there is also corresponding JavaScript that can be loaded and run automatically and used for the JavaScript hook; the mechanism is the same. For example, setup_ext.js (<domino install>/data/domino/html/qphtml/skins/setup/scripts/) is used in the setup theme, and you can use this file to customize the administration pages, such as Create a Place, Site Administration, or Work with Templates.

Quickr_ext.js
In the directory, <domino install>/data/domino/html/qphtml/skins/quickr/scripts, you can find a JavaScript file named Quickr_ext.js. This JavaScript is used for the 8.5 theme hook, and you can write your own JavaScript code in it. (The UI framework of Quickr Domino 8.5.1 loads this file and runs the JavaScript code automatically.) 54

Listing 7 shows an example of the hooked method, window.q_AjaxUtils.get. When this method is invoked, a log message is printed in the console.
Listing 7. Example of window.q_AjaxUtils.get

var Quickr_TraceGetService = { main: function() { dojo.addOnLoad(function(){ window.q_ajaxutils_get = window.q_AjaxUtils.get; window.q_AjaxUtils.get = function() { var args = arguments[0]; console.log(args.url); window.q_ajaxutils_get.apply(this, arguments); } }); } } Quickr_TraceGetService.main(); Within the Quickr_ext.js files, you can also supplement the default Quickr 8.5 style sheet, for example, to add the codes in Quickr_ext.js to load your customized CSS file (see listing 8).
Listing 8. Load customized CSS file

var Quickr_LoadMyCSSFile = { main: function() { dojo.addOnLoad(function(){ var oHeadLoc = document.getElementsByTagName("head"); if (oHeadLoc.length > 0) { oHeadLoc = oHeadLoc[0]; var styleNode = document.createElement("link"); styleNode.setAttribute("href","/qphtml/skins/custom/Quickr85_supp.css"); styleNode.setAttribute("type","text/css"); styleNode.setAttribute("rel","stylesheet"); oHeadLoc.appendChild(styleNode); } }); } } Quickr_LoadMyCSSFile.main();

Quickr85_ext.js
As previously mentioned, some UI's still use the 8.2 theme, for example, the customization page and the member page. You can use Quickr85_ext.js in the directory 55

<domino install>/data/domino/html/qphtml/skins/quickr/scripts to hook or extend those UI's. Listing 9 shows an example of adding a new menu item to the customization wizard.
Listing 9. Add new menu time to customization wizard

var Quickr85ExtensionMgrUtil = { init: function() { //If this is the customize screen, let's add the extension stuff if (h_SetReadScene == "h_TailorIntroRead") { //after the page is loaded, run this. dojo.addOnLoad( function(){ //get the list of choices and add the new one var els = qp_getElementsByClassName("choices", "div", document.body); if (els && els[0]) { var el = document.createElement("a"); el.className = "customize-E0070AFB7E85FE33052568B0005C0CC7"; el.setAttribute("alt", My customization menu); el.setAttribute("title",My customization menu); var sTemp = My customization menu; sTemp += "<span>Demo the JS hook in 8.2 theme</span>"; el.innerHTML = sTemp; els[0].appendChild(document.createElement("hr")); els[0].appendChild(el); } } ); } } } Quickr85ExtensionMgrUtil.init(); Figure 41 shows the result.

56

Figure 41. Add a new menu item on Customize page

9 Other customizations
Let's now discuss a couple of other customizations.

9.1 Customizing notifications

The notification function can be used to notify users about information on a Quickr place. For instance, when a new place is created, an email notification can be sent to the place owner about the place being created; when new members are added to the place, an email can be sent to the new member as an invitation. In addition, when a new folder or document is created/modified, an email can be sent to selected members about this item; weekly or daily reports will be sent to subscribing members about the different activities on the Quickr server. Quickr 8.5 for Domino supports notification in both Text and HTML formats, and you can also customize your own notification templates. For more details, refer to the Product Documentation topic, Notifications Overview Configuration & Customization.

57

9.2 QPAPI
QPAPI uses XML to access the Quickr for Domino Java API and, by doing so, it lets you perform a number of actions, such as searching all places in the service, getting a list of all places on a particular server, creating a new place, or adding a new person or group to a place. There are no significant changes to the QPAPI in Quickr 8.5 for Domino. For detailed information and samples, refer to the wiki articles, Accessing the Java API from a command line" and Accessing the Java API from a Java program.

10 General tips and precautions

Here are some useful tips to keep in mind: Firebug is a good tool to help you analyze Web pages and debug JavaScript code. With Firebug, you can inspect a selected DOM element, and the Widgetid can give clues about the Quickr Dijit that is being used. Fiddler is a good tool to capture/generate Web traffic for test and analysis. For performance issues we use .xsl and JavaScript compaction and concatenation, but it is not convenient for debugging and analysis. You can disable the compaction and concatenation functions by setting <qxsl enabled=false>, <qwidgets enabled=false>, <qdojo enabled=false> in the qpconfig.xml file. You then need to restart the http server. Lotus Quickr supports offline mode. From the customization perspective, offline has some impact in that some customization codes will not be deployed to the offline server automatically, and some will not work in offline mode (see table 19).

Table 19. Deploy customization in offline mode Items Deployed automatically? Customized theme (in .nsf file) External Js, css files Yes No Customized form, fields (in .nsf file) Yes

Can work directly? Yes Yes No, you must deploy these files to the offline server manually. (Copy these files to the same directory as online server.) No, you must deploy it to the offline server manually. No, only a form Placebot can be run in offline mode. Make sure the Placebot is not a scheduled agent. DOLS does not support scheduled agents. Check that the two groups (DOLS_Restricted_Agents and DOLS_Unrestricted_Agents) that were set up for DOLS are set correctly and make sure that their security settings are correct.

dll placebot

No Placebots created in a place will be taken into offline server automatically. For external agents, they won't.

58

Refer to the product documentation topic, Running PlaceBots offline.

11 Conclusion
This white paper has summarized some common customizations to Lotus Quickr 8.5 for Domino, explaining how to create a new 8.5 custom theme, how to apply it to a place, and how to migrate a customized place or template from the 8.2 theme to the 8.5 theme.

12 Resources
Refer to chapters 4 and 11 of the IBM Redbooks publication, Customizing QuickPlace. Read the developerWorks Lotus article, Introducing IBM Lotus Quickr REST services." Refer to the developerWorks Lotus Quickr product page. Refer to the developerWorks Lotus Quickr documentation page. Participate in the discussion forum.

About the authors

Zheng Fei Guo is a Software Engineer based at IBM's China Development Lab in Beijing, where he has been working on Lotus Quickr for Domino for the past several years. You can reach him at guozf@cn.ibm.com. Albert Wang is a Software Architect based at IBM's China Development Lab in Beijing, where he serves as the Lotus Quickr Domino Architect and Tech Leader. He has written five Chinese books on computer programming and has published more than 30 papers on computer technology for international conferences and academic journals. You can reach him at wangxu@cn.ibm.com.

Trademarks developerWorks, Domino, IBM, Lotus, Quickr, and Redbooks are trademarks or registered
trademarks of IBM Corporation in the United States, other countries, or both. Microsoft and Windows are registered trademarks of Microsoft Corporation in the United States, other countries, or both. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc., in the United States, other countries, or both. Other company, product, and service names may be trademarks or service marks of others.

59