Customizing themes in IBM® Lotus® Quickr™

Customizing themes in IBM® Lotus® Quickr™
services for IBM Lotus Domino® 8.1
Level: Intermediate
Bill Rodrick ([email protected])
Software Developer
IBM Software Group
Westford, MA
October 2008
© Copyright International Business Machines Corporation 2008. All rights reserved.
This white paper provides an overview of the default standard place theme used in IBM®
Lotus® Quickr™ services for IBM Lotus Domino® version 8.1, hereafter referred to as
“Quickr 8.1”. The paper examines the details you need to perform customizations of this
theme, focusing on a description of the Quickr 8.1 theme and how it works, as well as
how to create a custom theme based on the default theme. Also included is a description
of skin components new to Quickr 8.1, as well as a brief section on customizing the home
page.
Contents
1. Prerequisites.................................................................................................................. 3
2. New in Quickr 8.1......................................................................................................... 3
2.1 Style sheets and (partial) backward compatibility .................................................... 3
2.2 AJAX and expanded use of JavaScript..................................................................... 4
2.3 New member management UI .................................................................................. 4
2.4 New skin components ............................................................................................... 4
2.5 Client-side localization ............................................................................................. 4
2.6 Cookies store folder view preferences...................................................................... 4
3. Anatomy of the Quickr 8.1 theme................................................................................. 5
3.1 Page structure............................................................................................................ 5
3.2 Files........................................................................................................................... 6
3.3 Localized style sheets and string resource files ........................................................ 6
3.4 Theme-specific JavaScript support: Quickr81.js ...................................................... 7
3.5 HTML files ............................................................................................................... 8
3.5.1 Listfolder.htm..................................................................................................... 9
4. Cookies used by the Quickr 8.1 theme ....................................................................... 11
5. Skin components used in the Quickr 8.1 theme.......................................................... 12
5.1 DragAndDrop ......................................................................................................... 12
5.2 PriorityActions, RoomActions, SceneActions, FolderActions............................... 13
5.3 NewObject .............................................................................................................. 13
5.4 Customize ............................................................................................................... 13
5.5 ExpandableFolders.................................................................................................. 13
5.6 FolderAtomFeed ..................................................................................................... 14
5.7 FolderAtomFeedUrl................................................................................................ 14
5.8 FolderItemsPerPage ................................................................................................ 14
6. Creating a custom theme............................................................................................. 14
6.1 Getting started......................................................................................................... 14
6.2 Create your theme ................................................................................................... 15
6.3 Modifcation 1: Change the color scheme .............................................................. 17
6.4 Modification 2: Change the branding .................................................................... 20
6.5 Modifcation 3: Add expandable folders to left navigation section........................ 21
6.6 Last step: Create a template (PlaceType) using your theme................................... 27
7. Alternate approaches................................................................................................... 27
7.1 Upload your own versions of Quickr81.css and Quickr81.js ................................. 27
7.2 Create a directory for your custom theme on the server......................................... 29
7.3 Make changes to the standard theme on the server................................................ 29
7.4 Replace or supplement the standard theme’s CSS................................................. 30
7.5 Supplement the standard theme’s JavaScript......................................................... 31
8. General tips and precautions....................................................................................... 32
9. Customizing the home page........................................................................................ 32
10. Conclusion .................................................................................................................. 33
11. Resources .................................................................................................................... 33
12. About the author ......................................................................................................... 33
1. Prerequisites
It is assumed that your Quickr 8.1 server is running Hotfix 8.1.0.1 or above, available
from Fix Central.
To get the most from this paper, you should have a good working knowledge of basic
HTML, cascading style sheets (CSS), and JavaScript™. In addition, you should be
familiar with chapters 4 and, optionally, chapter 11, of the IBM Redbooks® publication,
Customizing QuickPlace, which describe the procedures for creating custom themes and
templates, respectively.
Although much of the material is not relevant to the Quickr 8.1 theme, the chapters
provide essential information on Skin Components, the different types of HTML files
used in a theme, and the method of uploading theme files and creating templates (a.k.a.
PlaceTypes).
2. New in Quickr 8.1
Those of you who are former Lotus Quickr 8.0 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.1 theme is a significant departure, as it is derived from a
new, cross-product design that will eventually be common to most IBM Lotus Web
clients, like IBM Lotus Connections, for example. As a result, most of the HTML used in
the version 8.1 theme–and almost all of the CSS–bears little or no resemblance to that
used in either Quickr 8.0 or QuickPlace.
2.1 Style sheets and (partial) backward compatibility
In Quickr 8.1, many of the elements in the “content” area of a typical page (as opposed
to the elements comprising the page layout in the theme’s HTML files) have a class
attribute containing one of the old QuickPlace style sheet selectors as documented in
section 4.2.2 of Customizing QuickPlace (sometimes in addition to a newer class name).
In most cases, this ensures some degree of compatibility with style sheets used in older
themes, including many older custom themes. There are, however, exceptions to this,
and backward compatibility should not be assumed when designing a custom theme.
In addition, there have been a number of changes to the structure of the HTML, both in
the dynamically generated page content as well as in the static structure of the theme
itself. All this is especially true of folder views, which include the Members page.
Note that some QuickPlace and Quickr 8.0 themes are included in Quickr 8.1 for
backward compatibility 1 . These older themes have been modified so as not to “break” on
Quickr 8.1, but full version 8.1 functionality is available only in the Quickr 8.1 theme.
For this and all the above reasons it is generally recommended that new custom themes
be based on the default version 8.1 theme. This is beneficial both from a performance
1
You may or may not see some or all of these older themes on the “Choose a Theme” page, depending on
the settings (or lack thereof) of the new <themes> section in your server’s qpconfig.xml.
and functional standpoint, and also ensures greater compatibility with future Quickr
releases.
2.2 AJAX and expanded use of JavaScript
Along with these changes in styling, the Quickr 8.1 theme employs a programming
model that uses Asynchronous JavaScript + XML (AJAX) techniques, Representational
State Transfer (REST) APIs, Web services, and Dojo 2 widgets to achieve greater
responsiveness and ease of use in several key areas.
In general, whereas older themes made liberal use of the QuickPlace skin components
to generate most of the page content on the server, the Quickr 8.1 theme is structured to
make asynchronous requests to the server to get data in XML or JSON (JavaScript
Object Notation) format. Also, it uses several JavaScript support libraries to parse the
data and generate the page content (HTML) on the client.
Again, this is most noticeable in folder views and thus, for those familiar with QuickPlace
or Quickr 8.0 theme development, in listfolder.htm specifically (see more on this
file is below).
2.3 New member management UI
The Quickr 8.1 theme supports the new Quickr 8.1 member management UI, which uses
all the above-mentioned techniques to provide a faster, easier-to-use method of adding
and managing members and controlling access to the place, without leaving the main
Members page. This is not available in other themes.
2.4 New skin components
Despite the fact that the Quickr 8.1 theme relies less on skin components and more on
JavaScript to render elements on the page, there are some skin components that were
introduced in Quickr 8.0 and Quickr 8.1 and thus are not documented in Chapter 4 of
Customizing QuickPlace. These are described in a separate section below.
2.5 Client-side localization
The Quickr 8.1 theme supports localization on the client side, in the form of localespecific style sheet and string resource files. This makes it easier to develop a theme
that can dynamically adapt to different language environments.
2.6 Cookies store folder view preferences
The Quickr 8.1 theme uses user- and folder-specific cookies to store various folder view
preferences selected by the user, for example, column sort order and the state of the
Folder Navigator (open or closed).
2
The 8.1 release uses Dojo 0.4.x.
3. Anatomy of the Quickr 8.1 theme
Lets’ now discuss some of the elements that make up the Quickr 8.1 theme.
3.1 Page structure
Figure 1 3 shows the page structure of the common UI framework, below which are the
classes and IDs of the main components on the page.
Figure 1. Page structure
lotusFrame
lotusBanner
lotusTitleBar
lotusPlaceBar
lotusMain
lotusColLeft
3
4
Top level container
Contains branding and global links
Contains application links and search
Contains place name (link)
Contains the page columns
Optional, contains menu and filters 4
Courtesy of Karl Thompson.
This generally does not appear on an “Edit” page (i.e., when the page layout is based on Edit.htm)
Optional, contains lists 5
Contains main content
Contains helper links
contains legal information 6
lotusColRight
lotusContent
lotusFooter
lotusLegal
3.2 Files
All files comprising the Quickr 8.1 theme reside on the Quickr server, in or under the
path qphtml/skins/quickr81.
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 1. Files comprising the Quickr 8.1 theme
File
Page.htm
Edit.htm
Listfolder.htm
Headlines.htm
Slideshow.htm
Stylesheet.css
Quickr81.css
Quickr81Strings.js
Quickr81.js
*.gif
Location
qphtml/skins/quickr81
Description
The basic theme layout, used when
viewing pages and documents, etc.
The other HTML files are variants
of this file.
qphtml/skins/quickr81
Basically a simplified version of
Page.htm, used for page layout
when editing something.
qphtml/skins/quickr81
See special section below.
qphtml/skins/quickr81
Page layout of “Headlines” folders.
Uses the HeadlinesFolder skin
component to provide a tabbed
interface to pages.
qphtml/skins/quickr81
Page layout of “Slide Show”
folder. Similar to Headlines.htm
but no tabbed interface; uses
paging controls only.
qphtml/skins/quickr81
Unused, but available for use in an
Quickr 8.1-based custom theme.
7
qphtml/skins/quickr81/nls/en Theme-specific, localized style
sheet
qphtml/skins/quickr81/nls/en Theme-specific, localized strings
qphtml/skins/quickr81/scripts Theme-specific JavaScript support
qphtml/skins/quickr81/images Theme-specific image files
3.3 Localized style sheets and string resource files
The Quickr 8.1 theme uses a theme-specific style sheet called Quickr81.css, plus a
number of style sheets that are common to Quickr as well as other to IBM Lotus
5
Unused in Quickr 8.1
Unused in Quickr 8.1
7
Replace “en” with the appropriate locale as appropriate.
6
products with a "thin client" Web experience, such as Lotus Connections. At this writing,
8
these files are core.css, defaultTheme.css, and iehacks.css .
Each locale has its own version of each of these files, in a separate directory under an
nls directory named, for example, “en” 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/quickr81/nls/en
The directory for the common style sheet files is:
qphtml/skins/common/themes/nls/en
Each of these directories also contains a file of localized strings written in JSON
notation, Quickr81Strings.js and QuickrCommonStrings.js, respectively.
Most of the strings reside in the common file, since there are not many theme-specific
strings in use in the standard Quickr 8.1 theme.
When generating a page, the Quickr 8.1 server loads the common “legacy” style sheet
(stored in a Notes subform called h_CommonStyleSheet in
domino/data/LotusQuickr/AreaTypes/HaikuCommonForms.ntf) and the
current theme’s stylesheet file(s), stored in resources.nsf.
The common style sheet has had a number of Quickr 8.0 and 8.1 style rules added to it,
so as not to “break” the older themes shipped with Quickr 8.1. This arrangement has
only been retained so as to maintain backward compatibility with older themes, and may
be changed in a future release for simplicity’s sake.
The common “legacy” style sheet cannot be used by the Quickr 8.1 theme, so the link to
it is dynamically removed from the <head> before the page is displayed. Unfortunately,
the theme’s own style sheet file(s) (for example, stylesheet.css) are unloaded at the
same time, because the two cannot be separated by the server.
This is one reason why the Quickr 8.1 theme’s stylesheet.css is empty, and
Quickr81.css resides in the file system and not in resources.nsf. Another
reason is that the server does not support localized style sheets loaded from
resources.nsf. As we will see, both these facts have consequences when creating
a custom theme based on the Quickr 8.1 theme.
3.4 Theme-specific JavaScript support: Quickr81.js
The default Quickr 8.1 theme relies heavily on JavaScript code to create and manipulate
certain elements on the page. Quickr81.js contains most of the code to do this
specifically for the Quickr 8.1 theme, in the sense that it makes assumptions about the
structure of the theme’s HTML and the presence of certain elements on the page as it
loads.
8
Despite the name, this file does not contain “hacks” per se, but rather a collection of style rules that
address some of the anomalies of the Internet Explorer browser.
Quickr81SupportUtil.init() is where it all happens; each of the theme’s HTML files
includes a <script> tag calling this function before the page loads, so that the “legacy”
style sheets are immediately unloaded and replaced with the Quickr 8.1 style sheets.
After this, the function adds an “onload” function, to be called after the page is finished
loading (but before being displayed), yielding all the page manipulations necessary to
render various elements required by the context. After the page loads, a good deal of
this code is executed only if the place uses the Blog or Wiki template (a.k.a.,
PlaceType).
The rest is determined by which of the HTML files is used to generate the page
(page.htm, edit.htm, listfolder.htm, etc.) and what “type” of page it is, as
reflected (usually) in one or both of the variables h_SetReadScene and
h_SetEditScene, which are guaranteed to be defined on every page.
Quickr81SupportUtil.massageUI() contains most of the logic that determines the context
and “massages” elements on the page accordingly. In some cases, this might involve
nothing more than hiding or showing certain elements. In others – for example, in a
folder view – an additional asynchronous request for folder data is sent to the server
before displaying the page, so that the element with id pageContent can be updated
after the response is received.
A fair bit of code in Quickr81.js is dedicated to generating a context-dependent “More
Actions” menu (see figure 2) and, like other context menus in Lotus Quickr, this one is
generated dynamically. In the case of this menu alone, however, most of the menu
actions are “lifted” from hidden links on the page that were generated as a result of the
various “actions” skin components (see Section 2.4 “New skin components” above).
Figure 2. More Actions menu when viewing the contents of a folder
Whereas an older theme renders these actions as buttons, the Quickr 8.1 theme builds
them into a menu and creates an “onclick” event for the More Actions button already
present on the page when it loads.
3.5 HTML files
The Quickr 8.1 HTML files contain the layout for the Quickr version of the common page
structure shown above, using the new style sheets only. As in Quickr 8.0 and
Quickplace, the server ignores anything appearing between a <head> and a <body> tag,
including the <body> tag itself. Instead, the content of the HTML file, after it has been
processed on the server, is inserted into the <body> of the page as it is served.
A common feature of all the HTML files is the initial call to Quickr81SupportUtil.init,
which takes care of loading the new Quickr 8.1 style sheets and much more besides.
Also, to prevent the page from briefly appearing with an un-styled or incomplete look,
there is an outer <div> tag that is initially hidden and then made visible, only after the
entire page has loaded and the necessary manipulations done:
<div id="lotusFrame">
Although copies of all five HTML files are installed in qphtml/skins/quickr81 on the
server, they are there only to be distributed and used as templates for creating custom
themes. These files also reside in Domino/data/LotusQuickr/resources.nsf,
and when a place uses the default theme, it is these files that are loaded by the server’s
skin generator. However, when a custom theme is created, the HTML files are uploaded
via the Web UI and stored as attachments to your place’s Main.nsf.
3.5.1 Listfolder.htm
Among the five HTML files, Listfolder.htm deserves special attention, and the
pageContent skin component tag in particular: In any older theme, the server replaces
this tag with HTML and JavaScript that includes the actual content of the folder view:
<QuickPlaceSkinComponent name=pageContent>
In the case of the Quickr 8.1 theme, however, the server simply adds a <div> or <table>
tag to the page instead of the content itself. That HTML is subsequently generated on
the client side as a result of processing folder view data received as XML or JSON from
the server.
This happens once after the page first loads, and subsequently every time the user
clicks on any of the following elements:
•
•
•
•
•
•
•
•
A sort heading
A “Show...items” control
A paging control (First/Previous/Next/Last)
A view control (“Table of all entries”/”Details of all entries”)
A “twisty” to expand or collapse a response thread
The “Hide all Responses” or “Show all Responses” control (“Table of all entries”
view only)
Certain actions in the More Actions menu (for example, Delete).
Certain actions in a page’s pop-up context menu (for example, Delete, Check
Out.)
Instead of refreshing the entire page, a request is made for the relevant folder data, and
only the page content itself is refreshed.
3.5.1.1 Dojo Dialogs in Listfolder.htm
Listfolder.htm also contains several <form> elements embedded within Dojo “dialog
templates.” These are used in the new Quickr 8.1 member management UI and are not
available in any other theme. For example, the template contained inside this <div>
element:
<div dojoType="dialog" id="memberAnonDefDialog" bgColor="black"
closeNode="memAnonDefCloseBtn">
is parsed by Dojo when this statement (located in the <head> element) is executed:
dojo.require("dojo.widget.Dialog");
which generates the dialog that appears when the Grant Access to Everyone action in
the More Actions menu is selected (see figure 3) when you’re on the Members page.
Figure 3. Grant Access to Everyone dialog
These templates are included at the end of listfolder.htm, comprising everything
from these lines up to the end of the file 9 :
<!-- Hide dojo dialogs until needed -->
<div style="display:none;">
Although these dialogs are used only on the Members page, they are present in the
theme file because the Dojo 0.4.x parser requires the dialog template HTML to be
statically present on the page as it is loading, and it also works best when that HTML is
located directly inside the <body> element.
9
This dialog template HTML may be moved outside of listfolder.htm in a future release of Quickr, so
you should be prepared for the possibility of removing this code from your custom themes’
listfolder.htm at that point.
4. Cookies used by the Quickr 8.1 theme
Clicking on any of the AJAX-enabled folder view controls; that is, anything that changes
how the user chooses to view the folder entries, has the effect of storing the current
state of the view in a folder-specific cookie named
“prefs_placeName_folderUNIDfromURL” (for example,
“prefs_myPlace_47B91A2AC603E0340525670800167201”).
This cookie contains the user’s selections (plus default values where the user has not
made a selection) as an “escaped” JSON string containing the name/value pairs shown
in table 2.
Table 2. Name/value pairs
Name
ipp
start
sortCol
sortOrd
expState
expDocNo
view
Value
Number of entries per page (10, 20, …)
Document number of starting entry
Column number 10 of value to sort by
Sort order (ascending=0, descending=1)
Response expansion state:
All expanded: 0
All collapsed:1
Expanded specific thread: 2
Collapsed specific thread: 3
Document number of entry whose
responses are expanded or collapsed, if
value of expState is 2 or 3.
Determines whether to show entries as a
table or with details (table=0, details=1)
In addition, there is a separate, user-specific cookie named “prefs_quickr81_userName”
(e.g., “prefs_quickr81_John%20Doe”), that currently contains only the state of the
“Folder Navigator”. This setting applies to all folders in all places for a given user, such
that the navigator remains open or closed as the user navigates from folder to folder,
regardless of place (see table 3).
Table 3. Folder navigator settings
Name
fNav
Value
Folder Navigator closed: 0
Folder Navigator open:1
NOTE: The cookies described in this section are used only by the Quickr 8.1 theme (and
by custom themes based on it). Places using older themes do not “remember” the
various user settings and selections mentioned here.
10
For those familiar with Domino’s &ReadViewEntries URL parameter, this column number may not be
the same as the column number appearing in the DXL returned by such a request. Rather, it is the column
number as used by Quickr’s “folder proxy document” where Folder Options settings are stored. The
“folder” UNID used in the name of the cookie is actually the UNID of this proxy document.
5. Skin components used in the Quickr 8.1 theme
There is not quite as much reliance on skin components in the Quickr 8.1 theme as in
older themes, for the following reasons:
•
Most skin components generate <script> tags that don’t always mix well with the
containing HTML tags in which they would appear, that is, in some cases and on
some browsers, they would interfere with the formatting of elements on the page.
In some cases, the Quickr 8.1 theme’s HTML does contain these skin
components inside hidden elements, and the generated links (anchor tags) are
then removed and placed inside other elements after the page loads (the More
Actions menu is an example of this; see Section 3.4 on Quickr81.js).
•
In general, it goes against current design philosophy to generate an excessive
amount of HTML on the server; rather, the client requests the data, returned as
XML or JSON, and then generates the appropriate HTML on the client. An
example of this is the PageContent skin component (see Section 3.5.1 on
Listfolder.htm).
•
When the new style sheets common to various IBM Lotus Web client offerings
are used, the first element in a list of HTML elements is often required to have
the lotusFirst class. Currently, there is no support for this in the Quickr Domino
skin component architecture (this would require something like a firstFormat
attribute for the <QuickPlaceSkinComponent> tag), to supplement the existing
format and selectedFormat attributes.
Despite this, several new skin components were introduced in Quickr 8.0 or 8.1, and
thus have not previously been documented in any QuickPlace-related material. The
following subsections describe these skin components.
NOTE: The fonts, styling, and text depicted in the images below are taken from the
default Quickr 8.1 theme and may not reflect what is seen in an older theme, or in a
custom theme derived from Quickr 8.1.
5.1 DragAndDrop
The inclusion of this skin component generates the “drop zone” currently seen by default
on the Library page (see figure 4).
Figure 4. Library page “drop zone”
Note that the drop zone appears only if it has been enabled in the Quickr server’s
qpconfig.xml file; for example:
<ui_features enabled="true">
<drag_and_drop_files_applet enabled="true" authentication="any" />
</ui_features>
5.2 PriorityActions, RoomActions, SceneActions, FolderActions
These are simply more “granular” versions of the Actions skin component, which is still
supported. These components make it easy to give a different look to the various types
of actions present on a page.
Priority actions are typically used most often, depending on the context. In the
Quickr 8.1 theme, they’re shown with a green background:
Room actions are currently undefined.
Scene actions might be something like Copy or Move (the meaning of which is
dependent on the context).
Folder actions are typically limited to the “Folder Options” link. In the Quickr 8.1
theme, these actions usually appear under the “More Actions” menu (see figure 2
above).
5.3 NewObject
This component generates the link that appeared as the New or Create button in
Quickplace and Quickr 8.0:
5.4 Customize
This component generates the link that appeared as the Customize item of the TOC skin
component in Quickplace and Quickr 8.0:
Note that the Customize item of the TOC skin component is still present in Quickr 8.1,
but it is filtered out of the Quickr 8.1 theme.
5.5 ExpandableFolders
This component generates the Folder Navigator component:
5.6 FolderAtomFeed
In a folder view, this generates a link to an Atom feed. In the Quickr 8.1 theme, it
appears as the Subscribe item of the More Actions menu (see figure 2 above)
5.7 FolderAtomFeedUrl
In browsers that support it (for example, Mozilla Firefox), this generates an Atom feed
icon for the folder in the browser’s navigation bar:
5.8 FolderItemsPerPage
This generates the “Show…items” paging control:
Note that in the Quickr 8.1 theme, this skin component, along with the older navigation
skin component (First…Last), is used only when folder data is not requested using AJAX
techniques. This is true only in the case of the Tasks and Calendar pages.
6. Creating a custom theme
This section describes some methods of creating a custom theme based on the
standard Quickr 8.1 theme, using a sample custom theme whose files are available for
download (see the Download section of this paper).
We’ll begin by giving the theme a different color scheme, using CSS and some custom
images, and then re-brand the theme by changing the logo. Finally, we’ll make a
significant change to the left 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’ll 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 a production environment.
6.1 Getting started
To create a custom Quickr 8.1 theme, you must first create a place to which to apply the
theme. You can also use an existing place, but in any case you will probably want to use
this place as the basis for a template (a.k.a. PlaceType), so plan accordingly.
Next, you must obtain the six files that you’ll upload to your place: stylesheet.css,
page.htm, edit.htm, listfolder.htm, headlines.htm, and
slideshow.htm. These are located in the directory qphtml/skins/quickr81 in the
server’s file system. Although you may need to use someone with access to the Quickr
server’s file system to provide the files, you should be able to get them simply by
entering the URL of the file, for example:
http://serverHostName/qphtml/skins/quickr81/stylesheet.css
http://serverHostName/qphtml/skins/quickr81/listfolder.htm
The HTML files will, of course, appear as a relatively “empty” page in your browser, but
just view the page source (right-click and select View Page Source in Firefox or View
Source in 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, listfolder.htm).
TIP: 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.1 theme files obtained from your administrator.
6.2 Create your theme
Now let’s create the new theme from the six files. To do this, follow these steps (you
must use Internet Explorer as your browser, since the theme files must be uploaded
using an Active X control 11 ):
1. From most pages, click Customize this place, and then select 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 5).
11
This will change in a future release.
Figure 5. Page to which theme files are uploaded
3. Upload your copy of stylesheet.css. To do this, either click on the Browse
button and find and select the file, or drag and drop the file to the control (see
figure 6). The Generate box should automatically become unchecked when you
upload the file.
NOTE: Do not check this box. 12
12
If the “Generate” box is checked, Quickr will substitute a version of the file based on the default theme
that shipped with QuickPlace 2.0.8.
Figure 6. Uploaded Style sheet .css file
4. Repeat this previous step for all five remaining HTML files (page.htm,
edit.htm, listfolder.htm, headlines.htm, and slideshow.htm).
5. If you have a thumbnail image you wish to use for you theme, you may upload it
using the appropriate control:
Ideally, the image should occupy 80 x 60 pixels.
6. Double-check that all Generate boxes are unchecked.
You should now have a custom theme that is identical to the standard Quickr 8.1 theme.
Before going on, test your theme by applying it to the place:
1. Click on Customize this place, and select 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 and make sure everything looks as it should in the standard
Quickr 8.1 theme. If all is well, let’s now do some modifications to the theme.
6.3 Modification 1: Change the color scheme
In this example, we replace the “blue” color scheme with one sporting a reddish-brown
look 13 . To do this, we:
13
Thanks to Karl Thompson, who provided the modified styles, images, and a downloadable PDF
document showing a comparison of the colors used in the standard and modified themes (see the
“Downloads” section of this article).
1. Replace some gradient image files with another. These are one pixel wide
images that produce shaded backgrounds when repeated across an element, for
example:
2. Replace some image files with others, for example:
3. Change some hex color codes (for example, #6794cb) in the style sheet. Some
of these are font colors, others background and border colors, etc.
NOTE: 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.1 theme design.
Since Quickr81.css contains many styles that you can’t be without–regardless of the
customizations you make–one practical approach is simply to leave Quickr81.css
alone, and instead override existing style attributes as appropriate, in an additional style
sheet of our own.
In the standard Quickr 8.1 theme, the pre-8.1 “legacy” common style sheet and the
theme’s stylesheet.css are not used. As we’ve seen, however, the UI to create and
modify a custom theme still allows the uploading of a style sheet, mainly for reasons of
backward compatibility.
Even though the file you upload here is not loaded by a Quickr 8.1-style theme by
default, you can add a <link> tag in your theme's HTML files to force the file to be loaded
after the standard Quickr 8.1 style sheets.
To do this, simply insert the following line after the <script> tag at the top of the file that
contains a call to Quickr81SupportUtil.init (you may want to refer to the
listfolder.htm file included with the downloadable sample theme):
<link rel="stylesheet" type="text/css" href="stylesheet.css" />
Note that your uploaded style sheet need not be named stylesheet.css; you can
call it anything you want, as long as the extension is “.css”.
Your theme will now load the standard cross-product style sheets, the Quickr 8.1 style
sheet, and your custom style sheet, in that order. Following the usual CSS rules of
precedence, this means that any style attributes in your custom style sheet will override
those of the same name in any of the standard style sheets, except in the rare (or
possibly nonexistent) case in which an attribute in a standard style sheet includes an
“Important” declaration.
For example, let's say you want to change only the page background, and that you’ve
copied a custom background.png file to the directory from which you’ll be uploading
your HTML files. Now, if you put just this one selector in stylesheet.css:
body{background-image:url(background.png)}
and upload that file, this will override the body style’s background-image attribute
selector in Quickr81.css, and you’ll see the new background.
NOTE: This works because all image file names in a theme’s HTML and CSS files are
assumed to correspond to files included in the top-level directory of the theme, and
these files are automatically uploaded and attached to the theme's "skin group"
document in the place's Main.nsf every time at least one of the theme files is
uploaded. In order for this to happen, the file name must appear without a path name
preceding in the src attribute of an <img> tag, or in the url attribute of a style selector.
Now to change the color scheme in our custom theme: For your convenience–and
because there are so many style attributes that must be overridden–you can just replace
the empty stylesheet.css you uploaded in the previous step with the one included in
the downloadable sample theme files with this paper.
Before uploading your new stylesheet.css, however, you must also copy all the
sample theme’s image files (with extension .gif or .png) to your directory, so that they will
be uploaded as well.
Finally, click on your theme on the Custom Themes page, upload stylesheet.css,
click Next, and look at your place; it should now look something like that shown in figure
7.
Figure 7. Example color-modified place
At this point, we have done nothing but provide some new images and change the
values of some style attributes. Let’s move on…
6.4 Modification 2: Change the branding
This step is simple; all we do is replace the “Lotus Quickr” brand logo with another image
of your choice. The name of the standard logo file is logo.gif, and it’s located in
qphtml/skins/common/images:
Although you could just replace that file with your own, in this example we make the
change in the theme. In each of the five HTML files in the default theme, you’ll find this
<img> tag:
<img id="lotusLogo" alt="Lotus Software" src="/qphtml/skins/common/images/logo.gif"/>
In each of those files, replace that line with this:
<img id="lotusLogo" alt="Redbooks" src="red_logo.gif"/>
Note that you must remove the path name from the image file name. When you upload
the HTML files, red_logo.gif (assuming it’s in your upload directory) is uploaded as
well, and Lotus Quickr generates a Domino attachment URI for it, so that the resulting
<img> tag in the page source looks something like this:
../../../Main.nsf/$defaultview/EE3AC1C831656267852574C4006094AA/$FILE/red%5Flog
o.gif?OpenElement&1221493163
Now, edit your custom theme, upload all your modified HTML files, and take a look; only
the branding should be changed (see figure 8).
Figure 8. Example brand-modified place
Now we’re ready to make a significant modification to the theme. We do this by making
some more modifications to the HTML, plus some JavaScript programming.
6.5 Modification 3: Add expandable folders to left navigation
section
So far, in our custom theme, the “left navigation” component appears as follows:
The text links are generated by the TOC skin component, which appears in the theme’s
HTML files:
<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>}
postfixHTML={</ul></div></div></div>}
>
With this modification, we’ll add icons to the links; and if the item is a folder, the icon will
include a “twisty” that can be clicked to expand or collapse the folder hierarchy. In
addition, these folder icons will be drop targets for documents, when the user is on a
folder page.
To do this, we:
1. Add a link to the dynamic_toc.js JavaScript file in the HTML files that don’t
currently include it (this file contains most of the code implementing the
ExpandableTOC skin component).
2. Replace the TOC skin component with the ExpandableTOC skin component in
each HTML file.
3. Remove the ExpandableFolders skin component from the HTML files that include
it. This removes the Folder Navigator from the page, but we no longer need it
(although there are reasons to prefer this to the modification we are doing here).
4. Create and upload a theme-specific JavaScript file with the code that makes
some necessary changes on the page after it loads (but before it is displayed).
5. Add a few style rules to stylesheet.css.
Let’s start by making the HTML modifications. Again, you may want to refer to the files
included in the sample theme files.
First, add the link to dynamic_toc.js in each HTML file that doesn’t already have it
(page.htm and edit.htm):
<script type="text/javascript" src="/qphtml/html/common/dynamic_toc.js"></script>
Next, replace the TOC skin component with ExpandableTOC by commenting out the
TOC component (using standard HTML comments) and adding the code in Listing 1
after it.
Listing 1. Code to add
<div class="lotusMenu">
<div class="lotusBottomCorner">
<div class="lotusInner">
<div id="toc">
</div>
</div>
</div>
</div>
<QuickPlaceSkinComponent name=ExpandableTOC
prefixHTML={<div id="expandableTOC" style="display:none">}
postfixHTML={</div>}
>
What we’ve actually just done is to add an empty left navigation area, along with the
code that generates the left nav items. For now, the latter is hidden from view–the
purpose of which will become apparent after we’ve added some JavaScript in the last
step.
Now let’s comment out the ExpandableFolders (folder navigator) skin component in all
the HTML files in which it appears (listfolder.htm, headlines.htm, and
slideshow.htm):
<!-- NOT USED BY CUSTOM 8.1 THEME
<QuickPlaceSkinComponent name=ExpandableFolders format={<Item class="toc-text">}
prefixHTML={<div id="toc" style="display:none;">} postfixHTML={</div>}>
-->
In addition, we need to hide the Show Folder Navigator control itself:
This we can easily do by containing it within a hidden <div> (new code shown in blue):
<!-- NOT USED BY CUSTOM 8.1 THEME: hide rather than comment out, otherwise code in
Quickr81.js breaks -->
<div style="display:none">
<div class="lotusLeft">
<a id="fNavShow" href="javascript: void Quickr81SupportUtil.toggleFNav();"
style="display:none;">
<img border="0" src="/qphtml/html/common/folder.png" alt="Click to
show folders"/> Show Folder Navigator
</a>
<a id="fNavHide" href="javascript: void Quickr81SupportUtil.toggleFNav();"
style="display:none;">
<img border="0" src="/qphtml/html/common/hiddenfolder.png"
alt="Click to hide folders"/> Hide Folder Navigator
</a>
</div>
</div>
NOTE: In this case, we can’t simply comment this out because the Quickr 8.1 theme’s
JavaScript support code may expect to find these elements on the page and might throw
an error if they are not present.
If you like, you can upload the HTML files at this point and see what you end up with.
What you should see is an empty left navigation area (see figure 9).
Figure 9. Empty left nav area
Now comes the “interesting” (or esoteric) part: Why did we not simply place the
ExpandableTOC skin component inside the “toc” div, as the default Quickr 8.1 theme
does with the TOC component? Well, we could have, but the result would look
something like that shown in figure 10.
Figure 10. Discussion folder expanded to expose two subfolders
Why does each item appear to be “vertically padded” with extra space? Let’s look at the
generated code, shown in listing 2.
Listing 2. Generated code
Notice that the two divs outlined in red are the only ones that don’t have a <script>
associated with them (the one appearing immediately before the box actually “belongs
to” the h_Library div). These scripts are generated by the ExpandableTOC skin
component and look like this (which is truncated):
This function call is what generates the actual HTML for the TOC item, and each of the
initial items has one of these. The reason the subfolder items (those inside the box) do
not is because their HTML was generated dynamically on the client, after requesting and
receiving the appropriate data asynchronously (AJAX-style) from the server. You can
see there is no unwanted padding around the two subfolders.
So the culprit here turns out to be the <script> tags; in some contexts, they can actually
create visual space on the page, and we must remove them in order to remove that
space. Since it’s not (easily) possible to delete script tags from the page, and hiding
them with CSS doesn’t work, we’ll take the approach of initially hiding the generated
HTML from the skin component, and then we’ll simply move the nodes we want into the
initially empty “toc” div, where they should be.
To do this, we introduce some JavaScript code into our theme, to manipulate the
appropriate elements. We do this inside a Dojo “onload” function, so that we know the
page has finished loading before we do our work (see listing 3):
Listing 3. JavaScript code inside the Dojo onload function
if (dojo && dojo.addOnLoad) {
dojo.addOnLoad(
function() {
var toc=dojo.byId("toc");
var eToc=dojo.byId("expandableTOC");
if (toc && eToc) {
// Move TOC items from the hidden ExpandableTOC Skin
Component div to div "toc".
// We do this so we don't have those <script> tags messing
up the formatting.
var tocItems=eToc.getElementsByTagName("div");
for (var i=0; i<tocItems.length; i++){
var tocItem2=tocItems[i].cloneNode(true);
toc.appendChild(tocItem2);
}
// remove Customize from TOC
tocItems=toc.getElementsByTagName("div");
for (var i=0; i<tocItems.length; i++){
if
(tocItems[i].getAttribute("unid")=="A6090949E584BB1105256708001671FE") {
tocItems[i].parentNode.removeChild(tocItems[i]);
}
}
// remove ExpandableTOC
eToc.parentNode.removeChild(eToc);
}
// Defeat the fNav setting in the prefs_quickr81_<user> cookie
// because we removed the Folder Navigator and the "toc" div
// is now the ExpandableTOC component and must always be visible:
toc.style.display="block";
}
);
}
This code does the following:
•
•
•
•
Makes a copy of each ExpandableTOC item (which happens to be a <div>).
Appends the copied divs to the “toc” div.
Removes the “Customize” div (because that’s a separate component on the page
in the Quickr 8.1 theme).
Makes the “toc” div visible, regardless of the value of the cookie that determines
the visibility of the Folder Navigator, which also must exist inside a div whose id
is “toc”. This, by the way, is the reason we had to remove that Folder Navigator
from the page; we can’t have two elements sharing the same id. Luckily, the
navigator would have been redundant in this custom theme anyway.
We could put this code inside a <script> tag inside each of the five HTML files, but to
avoid duplication, we put it inside a separate file called Quickr81Custom.js, which
we load in the HTML files. You’ll find this file included in the download accompanying
this paper. Put it into your upload directory, add the following lines to all five HTML files:
<img src="Quickr81Custom.js" style="display:none"/>
<script type="text/javascript" src="$FILE/Quickr81Custom.js"></script>
and upload all your HTML files once again. You should now see something that looks
like figure 11.
Figure 11. Navigation section without vertical padding
So we’ve removed the superfluous padding, but the font size is incorrect, the
background of the selected item looks bad, and we should reintroduce just a bit of visual
padding between the items.
Let’s fix this by adding the following lines to our stylesheet.css file and uploading
that file one more time (this additional code is contained in stylesheetExpTOC.css in
the sample theme archive):
#toc {border: none;}
#toc a, .toc-text, a.toc-text{font-size: 1em;}
.toc-bg {margin: .5em 0;}
.tocSelected-bg {margin: .5em 0; background-color: transparent;
padding: none;}
Now it should look something like figure 12.
Figure 12. Finished navigation section
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 customizations into your theme.
6.6 Last step: Create a template (PlaceType) using your theme
If you’ve created a custom theme that you intend to be used 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.0, and is described in chapter 11, “Creating PlaceTypes and a Turnkey Server” of the
IBM Redbooks publication, Customizing QuickPlace.
7. Alternate approaches
The methods for creating a custom Quickr 8.1 theme described in the above examples
can be varied and extended in certain ways. Before creating a custom theme to be used
in a production environment, you should evaluate the following approaches and decide
which of them–or even a combination thereof–might work best for you.
7.1 Upload your own versions of Quickr81.css and Quickr81.js
Even if you don’t have access to the Quickr server’s file system, you can use your own
versions of Quickr81.css and/or Quickr81.js, if you wish. This has the following
advantages:
•
With your own copy of Quickr81.css replacing the standard file, you won’t have
the extra overhead of loading a separate style sheet with styles to override the
default ones, as we did in the example theme by using stylesheet.css. This
could be significant if you need to make lots of changes to the theme’s styling.
•
You can add code (for example, the onload function used in this paper’s sample
theme) to your version of Quickr81.js rather than loading a separate JavaScript
support file (for example, Quickr81Custom.js in the sample theme).
•
Assuming you have a good knowledge of JavaScript, you can modify the way in
which pages are manipulated after loading. For example, you can change the way in
which the “More Actions” menu is created, add items to it, etc., by following these
steps:
1. Obtain copies of the following files, either from someone with access to the
server’s file system, or by entering the files’ URLs in your browser and saving
them to your desktop:
http://serverHostName/qphtml/skins/quickr81/nls/en 14 /Quickr81.css
http://serverHostName/qphtml/skins/quickr81/scripts/Quickr81.js
2. Put the files into your top-level theme directory (the one from which you’ll be
uploading) along with your HTML files.
3. If you are uploading Quickr81.css, add this line in all five HTML files after the
<script> tags at the top of the file (just like you did with stylesheet.css in the
example theme):
<link rel="stylesheet" type="text/css" href="Quickr81.css" />
Once you’ve done this, you must also upload a modified copy of Quickr81.js,
so that you can disable the default loading of Quickr81.css from the server’s
file system. To do this, change this line in your copy of Quickr81.js:
QuickrLocaleUtil.loadCssFiles("/qphtml/skins/quickr81", "Quickr81.css");
to this:
QuickrLocaleUtil.loadCssFiles();
This ensures that only the common CSS files (core.css, etc.) are loaded by
this function.
4. If you are uploading Quickr81.js, replace this line in all five HTML files:
<script type="text/javascript"
src="/qphtml/skins/quickr81/scripts/Quickr81.js"></script>
with these two lines:
14
Substitute the appropriate language code as necessary.
<img src="Quickr81.js" style="display:none"/>
<script type="text/javascript" src="$FILE/Quickr81.js"></script>
5. Upload the modified HTML files and the theme’s “empty” stylesheet.css to
the place you created, following the steps outlined in Section 6, “Creating a
custom theme” above. The “trick” <img> tag and the <link> tag you added will
cause your local Quickr81.css and Quickr81.js to be uploaded as well.
You should now have a custom theme identical to the standard Quickr 8.1 theme.
TIP: One quick way of checking that your uploaded files are being used is to use the
Firefox browser with Firebug installed. Check the files listed in the Scripts and CSS tabs
to see from where they’ve been loaded; if the URL contains “Main.nsf”, you are using the
uploaded files.
7.2 Create a directory for your custom theme on the server
If you have access to the Quickr server’s file system, you may wish to create a new
directory for your theme on the server. All the advantages of the alternate approach in
Section 7.1 apply, along with the following:
•
Your theme can support more than one locale, since you can have multiple
directories under your theme’s nls directory containing locale-specific copies of
Quickr81.css and/or Quickr81Strings.js.
•
You can make changes to your CSS and JavaScript without uploading any files to
test them, making development and maintenance of your theme faster and easier.
To do this, follow these steps:
1. Assume that your theme is to be called “myTheme” and copy the entire
qphtml/skins/quickr81 directory to a new one called
qphtml/skins/myTheme.
2. Edit your copy of Quickr81.js by changing all occurrences of
“qphtml/skins/quickr81” to “qphtml/skins/myTheme”.
3. Repeat the previous step for all locale-specific copies of Quickr81.css.
4. Repeat the previous step for all five HTML files in your theme directory.
5. Upload these HTML files and the theme’s “empty” stylesheet.css to the
place you created, following the steps outlined in Section 6, “Creating a custom
theme” above.
You should now have a custom theme identical to the standard Quickr 8.1 theme.
7.3 Make changes to the standard theme on the server
This approach is mentioned only for the sake of completeness. It is fraught with peril, but
if you have access to the server’s file system, you can of course make changes directly
to Quickr81.css, Quickr81.js, the image files, and any other files in any theme
directory (including the common theme directory).
Note that you should do this only if the customizations you want to apply cannot
realistically be made in the context of a template (PlaceType) from which places will be
created.
For example, if you already have a large number of places using the standard theme,
and want to make some kind of global modification–one that will affect all users in all
existing or future places–then you might consider making this change directly in the
theme files on the server (see table 4).
Table 4. Some cases in which this alternate approach might be appropriate
You want to:
Add a standard item to the “More Actions”
menu.
Replace the IBM Lotus logo with your
company’s logo.
Change a background color or image
How to do this:
Modify code in Quickr81.js.
Replace logo.gif in the
quickr81/images directory with a new
file of the same name.
Modify the appropriate style in
Quickr81.css.
Change a language-specific string
Modify the appropriate string in
Quickr81Strings.css (Currently, only
Add a language-specific string that can be
used by your custom code.
a minority of strings are stored here).
Add the string to
Quickr81Strings.css
If you do this, you must remember the following:
•
•
•
•
Do not modify the HTML files. These changes will not take effect (the HTML files
loaded by the server reside in resources.nsf) and will be detrimental to
anyone creating a custom theme that is supposed to be based on the standard
files.
If you modify any files here, realize that users obtaining those files from your
server–in order to use them in custom themes–will be basing their theme on your
modified versions of the file(s).
Make a backup of any file you modify–both the original and modified versions.
After upgrading to a new version, you will need to restore your modifications to
the new versions of the file(s). This may or may not be the case after installing a
Hotfix.
7.4 Replace or supplement the standard theme’s CSS
This approach is a safer, “gentler” alternative to the one described in section 7.3. It takes
advantage of an optional JavaScript “extension” file used in conjunction with the Quickr
8.1 theme only.
This file must be named Quickr81_ext.js and located in
/qphtml/skins/quickr81/scripts, along with Quickr81.js. If this file is
present, it will be loaded by Quickr81SupportUtil.init(), after the Quickr 8.1 style
sheets have been loaded (as we’ll see, the order of loading is significant).
Quickr81_ext.js will never be overwritten when you upgrade or apply a hotfix to
Lotus Quickr.
You can replace the default Quickr 8.1 style sheet (Quickr81.css) as follows:
1. In qphtml/skins/quickr81/nsl/en 15 , create an alternate style sheet copied
from quickr81.css, called, say, Quickr81_replace.css
2. In Quickr81_ext.js, add the following line of code, which will re-load the
common style sheets, plus Quickr81_replace.css for the user’s locale:
QuickrLocaleUtil.loadCssFiles("/qphtml/skins/quickr81",
"Quickr81_replace.css");
You can supplement the default Quickr 8.1 style sheet (Quickr81.css) as follows:
1. In qphtml/skins/quickr81/nsl/en, create an alternate style sheet copied
from quickr81.css, called, say, Quickr81_supp.css
2. In Quickr81_ext.js, add the code in listing 4, which will load
Quickr81_supp.css for the user’s locale:
Listing 4. Code to add to Quickr81_ext.js
var head = document.getElementsByTagName("head");
if (head && head[0]){
var lang = (QuickrLocaleUtil.getStyleLocaleList())[0];
var skinCss = document.createElement("link");
skinCss.rel = ("stylesheet");
skinCss.type = ("text/css");
skinCss.href = ("/qphtml/skins/quickr81/nls/"+lang+"/Quickr81_
supp.css"); head[0].appendChild(skinCss);
}
The advantage of supplementing versus replacing is that you create a style sheet with
only those things that need to be overridden in, or added to, the default theme's styles.
Also, page loads may be faster, because you're not linking to the common style sheets
twice.
7.5 Supplement the standard theme’s JavaScript
As mentioned in section 7.4, Quickr81_ext.js, if present, is loaded along with the
theme’s default JavaScript support file. If you wish to add code to modify or add
elements to the page as (or after) it loads, this is the place to do it.
Again, Quickr81_ext.js will never be overwritten when upgrading or applying a
Hotfix to Lotus Quickr, so your additions to the Quickr 8.1 theme’s JavaScript are safe
here.
15
Replace "en" with another language code as necessary, or perform step 1 in each section for each
language that will be used
8. General tips and precautions
•
If you use any of the alternate approaches described above and use your own
copy of Quickr81.js, do not change the names of any existing functions
or variables. In particular, do not rename Quickr81SupportUtil, because the
presence or absence of this object is used to determine whether a Quickr 8.1level theme is in use. If this object is missing, the new features of the Quickr 8.1
UI will not be available.
•
If you are a former QuickPlace user and have been using Domino Designer to
edit haikucommonforms.ntf to make changes in the UI, consider taking a
different approach. Study the way in which the functions in Quickr81.js
modify, add, or delete elements on the page, and put your own pagemanipulation code inside a dojo.addOnLoad() function, using one of the
approaches outlined above.
9. Customizing the home page
The home page (a.k.a. “landing”, “welcome,” or “My Places” page) uses its own theme,
called “setup,” which is based on the Quickr 8.1 standard place theme. The theme’s files
are found in qphtml/skins/setup on the server. Although there is currently no
provision for creating a custom version of this theme in which the theme’s HTML files are
modified, there are ways in which this theme can be modified to a certain extent.
Essentially, you can use the alternate approach in Section 7.3 above to make changes
to this theme’s CSS, JavaScript, and images. CSS changes can be made in
setup.css, images can be replaced in the themes images directory, and changes to
the theme’s JavaScript code can be made in setup.js.
In particular, you can add, delete, or change HTML elements by using the same
approach we used in our custom theme example, in which we introduced an “onload”
function to manipulate the left navigation elements after the page had finished loading.
Although this is, of course, a much more labor-intensive and roundabout approach than
simply writing HTML, it may suffice in certain cases.
If you like, you can put any page-manipulation code you write inside
QuickrSetupSupportUtil.init() in setup.js, inside this code block:
dojo.addOnLoad(function(){
QuickrSetupSupportUtil.massageUi();
// Put your code here
}
Alternatively, you can use similar approaches to those described in sections 7.4 and 7.5.
As of this writing, there is no support for something analogous to Quickr81_ext.js in
the “setup” theme 16 . In the meantime, however, you can add support for this yourself,
16
Check your server installation to see if this support has been added; look for a reference to “setup_ext.js”
in setup.js.
simply by adding the code shown in blue in QuickrSetupSupportUtil.init(), located in
setup.js (see listing 5).
Listing 5. Code to add in blue
init: function()
{
//override the css stuff for the OneUI
QuickrLocaleUtil.loadCssFiles("/qphtml/skins/setup", "setup.css");
//load an external js file
QuickrGeneralUtil.loadSupplementalScript("/qphtml/skins/setup/scripts/set
up_ext.js");
if (typeof(dojo) !="undefined") {
dojo.addOnLoad(function(){
QuickrSetupSupportUtil.massageUi();
});
}
},
Once you’ve done this, you can follow the approach described in sections 7.4 and 7.5 for
the Quickr 8.1 theme; that is, simply replace “quickr81” with “setup” in file and path
names, as appropriate.
10. Conclusion
This white paper has summarized some common customizations to the Lotus Quickr 8.1
theme for Domino. It has shown how to create a new theme and how to apply it to a
place, and has discussed the theme components and the role that each component
plays in the theme. Finally, the paper addressed individual theme sections and provided
examples of common customizations to modify the theme.
11. 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 documentation page.
•
Participate in the discussion forum.
12. About the author
Bill Rodrick is a Software Developer for IBM in Westford, MA, focusing on the UI for IBM
Lotus Quickr services for Domino. He’s also a part-time musician, luthier, and electronics
technician. He has studied linguistics, translation, and several languages, one of which
(Norwegian) he is fluent in. You can reach him at [email protected].
Trademarks
• Domino, IBM, Lotus, and Quickr, are trademarks or registered trademarks of IBM
Corporation in the United States, other countries, or both.
• Windows and Windows NT 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.