Professional Documents
Culture Documents
October 2008
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).
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.
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
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
Courtesy of Karl Thompson.
4
This generally does not appear on an “Edit” page (i.e., when the page layout is based on Edit.htm)
lotusColRight Optional, contains lists 5
lotusContent Contains main content
lotusFooter Contains helper links
lotusLegal contains legal information 6
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.
5
Unused in Quickr 8.1
6
Unused in Quickr 8.1
7
Replace “en” with the appropriate locale as appropriate.
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
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.
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.
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.
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:
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.
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.
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).
• 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).
<ui_features enabled="true">
<drag_and_drop_files_applet enabled="true" authentication="any" />
</ui_features>
Priority actions are typically used most often, depending on the context. In the
Quickr 8.1 theme, they’re shown with a green background:
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.
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.
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.
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
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:
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:
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.
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:
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):
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…
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:
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).
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.
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):
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.
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):
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).
Why does each item appear to be “vertically padded” with extra space? Let’s look at the
generated code, shown in listing 2.
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):
tocItems[i].parentNode.removeChild(tocItems[i]);
}
}
// remove ExpandableTOC
eToc.parentNode.removeChild(eToc);
}
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:
and upload all your HTML files once again. You should now see something that looks
like figure 11.
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):
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.
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.
• 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):
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>
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.
• 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.
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).
• 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.
You can replace the default Quickr 8.1 style sheet (Quickr81.css) as follows:
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:
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.
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.1-
level 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 page-
manipulation code inside a dojo.addOnLoad() function, using one of the
approaches outlined above.
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).
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."