customizationmigrationquickr8.5dominofinal
TRANSCRIPT
Customizing and migrating to IBM Lotus Quickr 8.5 for Domino
Zheng Fei Guo ([email protected])Software EngineerIBM Collaboration SolutionsIBM Software GroupBeijing 11, China
Xu Wang ([email protected])Software ArchitectIBM Collaboration SolutionsIBM Software GroupBeijing 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 Contents1 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 IntroductionLotus 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
2 Anatomy of the Quickr 8.5 themeBefore 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 structureFigure 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 componentsClasses IDslotusFrame Top level containerlotusBanner Contains branding and global linkslotusTitleBar Contains application links and searchlotusPlaceBar Contains place name (link) and “Place Actions”,
“Customize” button.lotusMain Contains the page columnslotusColLeft Optional, contains menulotusContent Contains main contentlotusFooter Contains helper links
Figure 2 shows the Library page in the 8.5 theme.
3
Figure 2. Library page in 8.5 theme
2.2 FilesAll 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 filesFile Location Descriptionpage.htm qphtml/skins/quickr The main theme layout used when viewing
pages and documents, and so on. It positions the main Quickr widgets.
listfolder.htm qphtml/skins/quickr Used for page layout (only used in “Members” page, an 8.2 theme remnant).
edit.htm qphtml/skins/quickr Used for page layout (used in “Folder Properties”, “Customize” and “Offline” pages, 8.2 theme remnants).
Stylesheet.css qphtml/skins/quickr Unused, but available for use in an Quickr 8.5-based custom theme.
qstyles.css qphtml/skins/quickr/theme Theme-specific, localized style sheet. It includes the Lotus oneui V2 css.
qstylesRTL.css qphtml/skins/quickr/theme The bidi (bidirectional) style sheet.qwidgets.js qphtml/skins/quickr/scripts Contains all Quickr for Domino widgets.
4
Quickr.js qphtml/skins/quickr/scripts Theme-specific JavaScript support. Used in page.htm.
qdojo.js qphtml/skins/quickr/scripts A Dojo package used in Quickr for Domino for performance purposes.
Quickr_ext.js qphtml/skins/quickr/scripts Available for use in a Quickr 8.5-based custom theme.
QuickrStrings.js qphtml/skins/quickr/nls Theme-specific, localized strings*.js qphtml/widgets Separate widget. “qwidgets.js” packs all of the
widgets under this folder.*.xsl qphtml/widgets XSL file used in 8.5 theme.
3 What's new in the Quickr 8.5 for Domino themeThose 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 layoutIn 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. Members (note that every user must go there to access their profile).2. Folder Properties (note that in v8.5, authors and editors can create folders and access this).3. Customize – the entire UI (Basics, Themes, Placebots, Forms, PlaceType options).4. 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”.
6
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 pageSteps Remarks Server or client behavior?1. The browser sends an http request.
For example, http://www.quickr.ibm.com/LotusQuickr/myplace
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.
For example,http://www.quickr.ibm.com/myplace http://www.quickr.ibm.com/Lotus Quickr/myplace/Main.nsf/h_Toc/4df38292d748069d0525670800167212/?OpenDocument
Server behavior
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.
Server behavior
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.
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
7
5. Client receives the response and executes the JavaScript, loading the related .js and css files.
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
6. Client initializes and renders the widgets. These widgets build up the whole page.
Some widgets will call Ajax to retrieve data from the server side, plus there will be some interaction between those widgets.
Client behavior
Server behavior (Makes response 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 Function QuickrSupportUtil.loadServerBase() Loads the q_base form that provides server
configurations to client side; for example, the information about the log-in user.
QuickrSupportUtil.loadCoreStyles() Loads the core style sheet files. It loads the qstyles.css.
QuickrSupportUtil.loadCoreDojo() Loads the core Dojo code. It loads /domjs/dojo-1.3.2/dojo/dojo.js. Lotus Domino provides the /domjs Dojo .
QuickrSupportUtil.loadSupplementalDojo() Loads the Dojo supplemental code needed by Quickr. It loads the //qphtml/skins/quickr/scripts/qdojo.js.
QuickrSupportUtil.loadQuickrWidgets() Loads Quickr widgets code. It loads /qphtml/skins/quickr/scripts/qwidgets.js.
QuickrSupportUtil.loadSTLink() Loads Sametime integration code. QuickrSupportUtil.loadMainUI() Performs some special initialization, for example, load
some necessary JavaScript.
3.2 WidgetsQuickr 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.
8
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 widgetsSkin components in Quickr 8.2 Widgets in Quickr 8.5<QuickPlaceSkinComponent name=TOC format={<li><Item></li>} selectedFormat={<li class="lotusSelected"><Item></li>} replaceString={Customize=&&Room Options=} prefixHTML={<div class="lotusMenu"><div class="lotusBottomCorner"><div class="lotusInner"><ul id="lotusTocEntryList">} postfixHTML={</ul></div></div></div>}>
<div class="lotusInner" dojoType="quickr.widgets.view.toc"></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 characteristicsWidget type Requests data from
server (feed)?Uses associated XSL to render itself?
Examples
Type 1 No No Message ViewerType 2 Yes No What's New, Group
ExpanderType 3 No Yes Link Page (creation)Type 4 Yes Yes 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.
9
Figure 6. Structure of Quickr widgets
3.3 Widget registryA 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
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).
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”
• “use”is 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
14
Widget Registry
TOC (Navigator)
State Tracker
Content controller
Action bar widgets Folder Page Tasks
Calendar Trash
etc.
BreadcrumbPage view
widgets Page Upload
Imported Linketc.
View widgets Library
Tabbed Folder Slide Show
Folder Index Tasks
Calendaretc.
Utility Classes and Objects Baseloader
AjaxUtils FolderUtils IconUtils
LocaleUtils GenUtils XmlUtils
NameUtilsetc.
Person CardLightbox widgets
Create Upload Create Imported
File Create Folder
Member Picker Send Link
etc.
Menu widgets Folder Actions Page context Folder context
Downloadetc.
Place Actions
Pop-up controller
3.4 AJAX and XSLThe 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
15
Quickr Server
Widget B
XSL Transform
Response(XML format, etc)
XSL
Widget A
AJAX (SOAP, REST) Response
apply to dom
Client side
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 modelQuickr 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. User clicks on the Navigator2. Event is generated to open the folder3. Page Controller fields event.4. Loads handler widget for folder5. Widget opens folder and displays6. Widget generates event for current state7. 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.5Event DescriptionACTION.OPENLASTVIEWORPAGE 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.
ACTION.GENERAL.BASECHANGED 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.
ACTION.MESSAGE.INFOACTION.MESSAGE.ERRORACTION.MESSAGE.CONFIRMACTION.MESSAGE.WARNING
These events are used to display informational messages to the user and are usually displayed above the document listing in a folder view.
ACTION.LOADING.SHOWACTION.LOADING.HIDE
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.
ACTION.DIALOG.OPENACTION.DIALOG.CLOSE
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.
3.6 Upgrade to use Dojo 1.3.2Quickr 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 filesQuickr 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 theme’s 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. Collect the new strings and add them in JSON format into those string-resource files.2. 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 customizationSeveral 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 settingsAttribute Value Default Descriptionrestrict_choices TRUE Only "allowed" and custom themes can be selected
on the "Choose a Theme" page.FALSE yes All themes may be selected on the "Choose a
Theme" page.allow_in_85_theme TRUE Make these settings apply even in 8.5-based
themes.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 themeNow 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.
We’ll 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, we’ll 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 startedTo 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 you’ll upload to your place: stylesheet.css, page.htm, edit.htm, and listfolder.htm. These are located in the qphtml/skins/quickr directory in the server’s file system. Although you might need to use someone with access to the Quickr server’s 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.csshttp://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. From most pages, you can select Customize – Custom Themes.
2. 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. Repeat the previous step for all three remaining HTML files (page.htm, edit.htm, and listfolder.htm).
5. 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. Select Customize – Choose a Theme.2. 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, let’s 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. Replace some image files with others.
3. 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 can’t 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 we’ve copied a custom background.png file to the directory from which we’ll 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 {background-image:url(/qphtml/skins/custom/images/titlebarLeft.png);}.lotusTitleBar .lotusRightCorner {background-image:url(/qphtml/skins/custom/images/titlebarRight.png);}.lotusTitleBar .lotusTabs li {background-color:#821413;border-color:#821413 #821413 #821413;}.lotusSpritesOn .lotusTitleBar {background-image: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. Upload a new logo file into the <domino>\data\domino\html\qphtml\skin\custom folder; we can then use this image in .css definition.
2. 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 we’re 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” functionIn 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;background-color:#ffffff;-moz-border-radius-bottomleft:0px;-moz-border-radius-bottomright:0px;-moz-border-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 codefunction 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
We’re done! Feel free to modify and expand on what we’ve 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 themeIf you’ve 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 formsThe out-of-the-box forms are sufficient for many uses, but you can also create your own forms if needed.
5.1 Creating new formsThere 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.5This 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 author’s machine.
• Polling result mode. The page is displayed in this mode when the cookie has been set on the author’s 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 formFirst we need to add some customized fields in the form, as compared in table 9.
30
Table 9. Customized fieldsPolling form in 8.2 theme 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>
<!-- 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>
<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 pageField Name Descriptionh_name The name of the poll is set in the system field h_name. This field
is set when the poll is created.c_IsDesigningPoll The user-defined field is used to check whether the form is being
designed.c_PollChoices This user-defined field stores the poll choices.c_VoteTally The results of the vote are stored in this user-defined field.c_PollInformation 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 modeTo 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 implementationsOld implementation New implementationfunction IsEditing( ) {return !(location.href.indexOf ('EditDocument') == -1);}
function IsDesigning( ){return (typeof (c_IsDesigningPoll) != "undefined" && c_IsDesigningPoll== '');}
function IsEditing( ) {return h_isBeingEdited;
}
function IsDesigning( ){return (typeof (c_IsDesigningPoll) != "undefined" && c_IsDesigningPoll== '');}
5.2.3 Design modeIf IsDesigning() returns true, the options for creating a poll will be displayed (see listing 3). Related codes can remain unchanged.
Listing 3. IsDesigning() codeif ( IsDesigning( )) {
// we are in edit mode - let's show the options for the votedocument.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 modeThe polling mode lets users who have not voted offer the vote (see table 12).
Table 12. Comparison of polling mode codesCodes about polling mode in 8.2 theme Codes about polling mode in 8.5 theme
// if the current user has not voted// offer the voteif ( !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"){
// if the current user has not voted// offer the voteif ( !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_CurrentChoiceVALUE="' + 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_CurrentChoiceVALUE="' + 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 modeThe third mode displays the results of the poll (see listing 4); related codes remain unchanged.
Listing 4. Sample polling result codeelse {
// write out the results of the polldocument.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 functionThe 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 functionsPolling submit function in 8.2 theme Polling submit function in 8.5 themefunction MyVoteSubmit( ) {SaveVote(G_CurrentForm);G_CurrentForm.h_SetEditCurrentScene.value = 'h_StdPageEdit';G_CurrentForm.submit( );}
function SaveVote( myForm){var i, j;// unpack the vote datavar 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 fieldmyForm.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 datavar 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 fieldmyForm.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.getPlaceName()+'/@R'+window.q_GeneralUtils.getRoomNSF()+'/@D'+unid+']" type="string">' + myForm.c_VoteTally.value +'</snx:field>'; window.q_DocFolderUtils.submitWithXmlRest("",unid,xml, function() {
// save the cookiewindow.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 functionThe 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 formfunction SaveDesignModeParams(myForm) {
// read the choicesvar 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 widgetsThis 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 DominoThis 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 linksThis 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 editorsAs 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 buttonsThis 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 itemsThis 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 viewThis 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 attachmentsThis 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 placeThis 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 drag-and-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. Create the widget file that is needed.2. Extend the widget registry.3. Subclass the defaultPage.js to add in new functionality.4. 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 cloudWhen 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 systemStarting 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 templatesQuickr 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 themeSince 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 htmls8.2 theme 8.5 themepage.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. Remove “slideshow.htm” and “headlines.htm”.
2. 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 formsSince 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 variableIn 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 QuickrCGIVariablesVar G_CacheCompliantUrlTemplate
window.q_BaseLoader.environment.cgiVariableswindow.q_BaseLoader.environment.cacheCompliantUrlTemplate
The following sample JavaScript variables are for log-in user configuration:
haiku.loginName = 'Qphotos'; haiku.userName = 'Qphotos';
var currentUserAccess = 6;
window.q_BaseLoader.user.loginNamewindow.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 QuickrQuickr 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 changesDojo 0.4 Ajax API Dojo 1.3.2 Ajax APIvar 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);
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 xhrGetvar 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 utilitiesUtility Descriptionwindow.q_GeneralUtils Provides some common functions, such as JSON parse,
get URL parameters, etc.window.q_BaseLoader Provides lots of server configuration and log-in user
information. window.q_AjaxUtils Encapsulates Dojo Ajax API and integrates with Quickr
authentication mechanism.window.q_CookieUtils Cookie-related functions.window.q_DateUtils Encapsulates Dojo Date API; used for date convert and
format.window.q_DocFolderUtils Encapsulates common APIs for operations on a doc
while in a folder view; provides some common functions such as remove, rename, move.
window.q_DocUtils Encapsulates common APIs for handle document, such as retrieve document entry information.
window.q_FolderUtils Encapsulates common APIs for handle folder, such as create folder, retrieve folder ACL information.
window.q_LocaleUtils Utilities to handle multi-locale issues.window.q_RestUtils Utilities to send Rest request; easy to build up a Rest
request.window.q_XmlUtils Utilities to handle .xml data; provides common functions
for parsed data from response of Web service.
JavaScript hook and eventA 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 menudojo.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 comparisonOld implementation (Construct the URL yourself)
var sUrl = "../../h_Index/$new/?EditDocument&Form=h_PageUI"; sUrl += "&PreSetFields=h_EditAction;h_New,h_SetReadScene;h_StdPageRead,h_SetEditScene;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 matrixTable 18 is the JavaScript API conversion matrix for the most common APIs.
52
Table 18. Conversion matrixFrom: To:
dojo.io.bind dojo.xhrGet \ dojo.xhrPost
dojo.date.format dojo.date.locale.format
dojo.event.connect()/dojo.event.disconnect() dojo.connect()/dojo.disconnect()
dojo.lang.* dojo.* (try to find the comparable here, for example, dojo.forEach() to replace dojo.lang.forEach())
dojo.widget.ComboBox dijit.form.ComboBox
dojo.widget.Tooltip dijit.Tooltip
dojo.widget.createWidget “new” the widget directlyFor example: new dijit.form.ComboBox({},
categoriesField);
QuickrXMLUtil.* window.q_XmlUtils.*, For example, replace QuickrXMLUtil.getNodeValuesByTagName() with window.q_XmlUtils.getDocTagValue()
QuickrLocaleUtil.* window.q_LocaleUtils.*,
For example, replace QuickrLocaleUtil.getStringResource() with window.q_LocaleUtils.getStringResource
QuickrGeneralUtil.* window.q_GeneralUtils.*For example, replace QuickrGeneralUtil.getDownloadLink() withwindow.q_GeneralUtils.getDownloadLink()
QuickrDateUtil.* window.q_DateUtils.*For example, replace QuickrDateUtil.convertDateTo8601String() with window.q_DateUtils.convertDateToISO8601String()
QuickrCookieUtil.* window.q_CookieUtils.*For example, replace QuickrCookieUtil.getCookie() with window.q_CookieUtils.getCookie()
QPAjax_Request window.q_AjaxUtils.postwindow.q_AjaxUtils.get
QPAjax_SubmitForm window.q_AjaxUtils.postMultipartForm
7.3 Using 8.2 unchanged customizations on an 8.5 serverIt'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 hooksQuickr 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 hookThere 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 hookQuickr 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.jsIn 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 filevar 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.jsAs 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 wizardvar 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 customizationsLet's now discuss a couple of other customizations.
9.1 Customizing notificationsThe 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 QPAPIQPAPI 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 precautionsHere 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 modeItems Deployed automatically? Can work directly?Customized theme (in .nsf file) Yes YesCustomized form, fields (in .nsf file) Yes YesExternal Js, css files No No, you must deploy these files to
the offline server manually. (Copy these files to the same directory as online server.)
dll No No, you must deploy it to the offline server manually.
placebot Placebots created in a place will be taken into offline server automatically. For external agents, they won't.
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.
58
Refer to the product documentation topic, “Running PlaceBots offline.”
11 ConclusionThis 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 authorsZheng 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 [email protected].
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 [email protected] .
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