Introduction to JotSpot Themes

This document addresses how to customize the look and feel of wikis running version 2.6 and 2.7 of the JotSpot service. In JotSpot, cascading style sheets (CSS) are used to control the layout and appearance of each page. To customize the look and feel of your JotSpot wiki, you can provide your own style sheet that overrides the default styles. For a more radical makeover, you can modify the template pages that generate the underlying XHTML.

Customizing your theme requires three steps:

1. Understand the maintenance requirements of a custom theme
2. Install the CustomTheme package in your wiki, and switch from standard to custom
3. Modify your CustomTheme's CSS and/or template pages to create your custom look and feel

With Control Comes Responsibility

When you customize your 2.6 wiki's theme, you assume a new responsibility. One of the benefits of the JotSpot hosted service is that new features and fixes are automatically delivered to your wiki. However when you change your wiki's look and feel by creating a custom theme, you're truly in control. We can no longer automatically deliver new user interface features and fixes without risking overwriting your changes.

Because of this, when you pursue a custom theme as documented here, you will need to add features or fixes that are delivered in future releases. In addition, future applications might rely on these standard theme elements, so future apps might not work correctly.

For a more complete explanation of this, please see this blog post, which discusses this in more detail.

Installing and Selecting your Custom Theme

A custom theme is actually a complete copy of the standard wiki theme. This allows you to change your custom theme, but always switch back to the standard theme with the flip of a switch.

To install the CustomTheme package:

1. Log into your wiki as admin, select Manage Packages from the footer menu, and install:
   • For 2.6 wikis, the attached CustomTheme-1.0.zip package
   • For 2.7 wikis, the attached CustomTheme27-2.7.0.zip package
2. Go to your footer menu and click "Other Settings"
3. Press the "switch themes" button and select Custom theme from the dropdown list. By default, this theme looks exactly like the "JotSpot default theme". Note: you can always revert back to the standard theme using this theme switcher.

At this point, your entire site is now using a custom theme, rooted at:

• /System/Themes/CustomTheme for 2.6 wikis
• /System/Themes/CustomTheme27 for 2.7 wikis

For example, the template that generates the XHTML for a wiki page is in /System/Themes/CustomTheme27/view. Template pages are normal wiki pages.

Now you can start to customize it. The mechanics of customizing the CSS and supporting images:

2.6 wikis:

1. Still on the "Other Settings" page, click the "customize theme" button,
2. You'll see a simple page with links to the css and image upload pages. Attach new versions of your stylesheet as a file named redesign.css here, and any images you need.
3. NOTE: these CSS and graphics attach pages use a hard-coded theme, and won't change when you upload new stylesheets/images. Test by refreshing WikiHome.

2.7 wikis:

1. Images and other files needed by your theme can be attached to the /System/Themes/CustomTheme27/graphics page and then referenced there as needed
2. The CSS is in a wiki page: /System/Themes/CustomTheme27/css/redesign.css.
   • to edit this page, add ?edit=1&editStyle=xml to the URL like so: /System/Themes/CustomTheme27/css/redesign.css?edit=1&editStyle=xml.
   • Note: there is no edit button for this page. If you simply go that that URL you will see: UnknownError: Additional information: com.s3.script.lib.JotLibException: function webspaceURL: parameter path: no value specified. This is because this page has some script in it that won't "run properly" when simply viewed as a normal page. It needs additinal context, which you can't provide by simply viewing the page.

Styling your Custom 2.6 Theme

To modify or create a theme, you need to be familiar with CSS syntax and have at a least rudimentary understanding of CSS structure and rules. The first step in creating a new theme is a design exercise, though--before you begin to set style attributes, you need to know what you want your pages to look like! Familiarize yourself with the basic page elements and spend some time creating comps of each page view and refining your design before you try to translate your design into CSS. Even if you just want to change a few colors and tweak a few styles, spending some time to think through the changes you want to make will make the process easier.

This document provides an overview of the Jot CSS Architecture and describes the various page elements you can control through CSS:

• Overview
• Jot CSS Architecture
• Header
• Login Info
• Search Controls
• Sidebar
• Content
• Footer
• View Mode
• Edit Mode
• Preview Mode
• Login Page
• System Pages

Sample alternate themes can be found on the JotRedesigns page.

CSS Overview

JotSpot uses the Cascading Style Sheet (CSS) technique often referred to as CSS table-less layout. All configurable page elements are positioned and styled through CSS. This provides a clear separation between the page content and presentation and makes the creation of different Jot themes possible. By simply adding your own style sheet, you can give your wiki a totally different look and feel. How different? If you haven't used CSS to control page layout before, here are some sites to get you thinking outside the (table) box:

• CSS Zen Garden Demonstrates what talented artists/designers can accomplish visually with CSS-based design.
• Remix MIX More examples of changing a site's look and feel through CSS. (Results of a Microsoft-sponsored contest, but most entries seem to be browser agnostic.)
• CSS Edge A set of demos that push the limits of CSS design.

There are lots of good CSS references and tutorials available on the Web, so there's no point in reinventing the wheel here. However, there are a couple CSS concepts that are key to making your Jot theme work:

• The CSS Box Model
• Descendent Selectors

Box Model

To use CSS to control page layout, you need to understand the CSS Box Model. For display purposes, every element in a document is considered to be a rectangular box that has a content area surrounded by padding, a border and margins. CSS defines two basic types of boxes: block and inline.

• Block elements are HTML tags that create a box on the page. Usually this means a line-break before and after. The tendency for most block elements is to fill, width-wise, all of the space available. Many block elements come with default margins or padding. Examples of block elements include <div>, <p>, <h1>, and <pre>.

• Inline elements don't create a line break--they stay with the flow of the current element. Inline elements fill up a space just big enough to fit the content. Examples of inline elements include <span>, <b>, <i>, and <a>. (Not all browsers agree on all tags. Some treat <img> as inline and some as block.)

Any element's "blockness" or "inline-ness" can be overridden by the CSS display property. In addition to display:block and display:inline there is also display:none, which removes the block and any space it contains from the page. This is different from setting visibility:hidden, which maintains space for the block but makes it invisible.

Descendent Selectors

To define styles for specific elements on a page, you need to understand how descendent selectors work in CSS. A CSS selector specifies the tag name or class or id attribute to which the specified style attributes will apply. For example:

//Set the color attribute for elements of class  "my-class"
.my-class { color: blue; }

//Set the color attribute for elements with the id "my-id"
#my-id { color: green; }

//Set the font-family attribute for all <p> tags
p { font-family: verdana, helvetica, sans-serif; }

Descendent selectors associate styles with the children of specific elements, providing a way to define styles for tags within tags. A descendent selector is specified as a list of CSS selectors, separated by spaces, that identify a particular sub-element. For example, the following CSS code defines a rule for all anchor tags inside of <th> tags within elements whose id attribute is jot-content:

#jot-content th a {...}

This syntax is what makes it possible to style the elements in the Jot header or sidebar independently from the elements in the content area or footer. For example, by defining a descendent selector like the one shown above, you can make the links in the content area look different from all other links without having to put anything into the HTML code.

CSS Resources

If all this talk of elements, attributes, and selectors has you in need of a CSS refresher, here are some resources you might find helpful:

• CSS Tutorial CSS nuts and bolts from W3Schools.com
• CSS Layout Techniques An introduction to table-less layout from glish.com
• CSS Selectors Detailed information about using CSS selectors from the fine folks at the W3C

Another resource that you'll find very useful as you start exploring the JotSpot CSS architecture is the Web Developer Extension for Firefox. This handy little extension enables you to interactively explore and modify the CSS of any Web page. The View Style Information and Outline functions provide an easy way to see what styles are applied to particular elements. The Edit function enables you to make changes to the CSS and see the results in real-time, without making any permanent changes (though you can save your changes to a file if you want).

Jot CSS Architecture

The following ids are used to identify the elements that define the basic structure of a Jot page:

#jot-canvas
  #jot-loginInfo
  #jot-search
  #jot-header
  #jot-main
    #jot-sidebar
    #jot-content
#jot-footer

The basic structure looks like this:

The loginInfo and search elements are positioned relative to the canvas, but by default are displayed in the header area:

To control the layout of these elements, you can set their width, position, margin, padding, float, z-index, visibility, and display properties.

You can control the appearance of these elements by defining background colors and images, borders, setting the font size, defining styles for sub-elements, and so on.

Using descendent selectors enables you to style elements in one container without affecting those elements if they occur in other containers on the page.

Page Types

There are five different body classes used for Jot pages:

jot-view - the main class used to display wiki pages.
jot-edit - used to display wiki pages in edit mode
jot-preview - used to display an edited page in preview mode
jot-view-loginpage - used to display the login page
jot-view-systempage - used to display system pages, such as errors

You can set different properties for particular page types through these body classes.

Defining a Custom Theme

1. Specify Defaults for the Basic Elements
html, body, td, a, form, h1, h2, h3

2. Define Properties for General Classes
errors, buttons, etc.

2. Customize the Header
Changing the logo
Setting a background image
See also jot-loginInfo, jot-search

3. Define Properties for the Sidebar Area

4. Define Properties for the Content Area

5. Define Properties for the Footer

6. Define Properties for Error Pages

7. Define Properties for the Login Page

Page Header

The default header is positioned at the top of the page and automatically scales to fit the width of the page. It contains the Jotspot Wiki logo and a link to WikiHome.

In the default layout, the loginInfo and search elements are displayed in conjunction with the header, but they can be positioned relative to the canvas independent of the header.

#jot-header

The jot-header style is applied to an H1 element within the jot-canvas div. As an H1, it's a block element that expands its width to fill the available space. The header element is used by the view, edit, preview, and system pages, but is not used on the login page (jot-view-loginpage class pages).

You can set properties on #jot-header to change the layout and appearance of the header. The jot-header element has two sub-elements:

• img -- controls the display of the default logo image
• a.wikiLink -- styles the link from the logo image

Migration Note: jot-header is equivalent to the old jot-pageName element.

#jot-header a.wikiLink

Controls the display of the link to WikiHome from the logo.

#jot-header img

Controls the display of the default logo image. To display your own logo, you can replace the default logo image, or hide the default logo image and set your logo as the background property of the #jot-header a element. See jot-header a.

Adding a Background Image to the Header

To use a background image in the header, set the #jot-header background property.

In the Citrus theme shown above, the image is set to repeat horizontally (repeat-x) to fill the available width as the window is resized.

For example:

#jot-header {
		background: url(citrus_leaves.jpg) repeat-x;
		...
	}

Adding a Custom Logo to the Header

You can replace the default JotSpot Wiki logo, or you can hide it and display your logo by setting a background image on the #jot-header anchor element.

For example, to set a background image on the header anchor element:

	#jot-header a {
		/* substitute your own logo for the url */
		background: url(citrus_logo.gif) no-repeat top left;
		position: absolute;
		top: 10px;
		left: 10px;
		height: 41px;
		width: 165px;
	}
	#jot-header a:hover{
		text-decoration: none;
	}
	#jot-header img {
	  visibility: hidden;
	}

Jot Login Info

The login info consists of the welcome user message and associated links (Preferences, Account Dashboard, and Logout). The login info can be positioned relative to the canvas independent of the header or search controls. In the default layout, the login info is displayed in the upper-right corner of the page above the search controls.

#jot-loginInfo

The loginInfo element is applied to a div that contains the welcome user message and user links.The loginInfo element is used by the view, edit, preview, and system pages, but is not used on the login page (jot-view-loginpage class pages).

Three sub-elements are used with jot-loginInfo:
strong
a.wiki_loginLinks
a.wikiLink

Migration Note: jot-loginInfo is equivalent to the old jot-topLoginInfo element.

jot-loginInfo strong

Controls the display of the user name in the login info.

jot.loginInfo a.wiki_loginLinks

Controls the display of the Preferences link in the login info.

jot-loginInfo a.wikiLink

Controls the display of the Account Dashboard and Logout links in the login info.

Search Controls

The search controls consist of a text label, text input field, and a submit button. The search controls can be positioned relative to the canvas independent of the header or login info elements. In the default layout, the search controls overlay the upper-right portion of the header.

#jot-search

The search element is applied to a form that contains the Wiki search controls. The search field and input button are only displayed in view mode (jot-view class pages).

Four elements are used with jot-search:

• label
• jot-searchBox
• input
• input.jot-submit

#jot-search label

Controls the display of the search controls.

#jot-search input

Controls the display of the search input field and submit button.

#jot-searchBox

Controls the display of the text input box.

#jot-search input.jot-submit

Controls the display of the search submit button. '

Sidebar

The sidebar contains a collection of mini windows that display:

• The Create Page button
• Favorites
• Recent Changes
• An Invite control
• Installed Applications

The sidebar on the WikiHome page also contains a link to getting started (oobe) information. Plugins can add additional item to the sidebar. The basic structure of the sidebar looks like this:

You can define a base style for the mini windows through the jot-miniwindow class. The following elements enable you to customize particular mini windows:

• #jot-favs
• #jot-changes
• #jot-invite
• #jot-apps

#jot-sidebar

The sidebar can be positioned relative to the main div within the canvas. In the default layout, the sidebar is displayed to the left of the content.

.jot-miniWindow

Controls the display of the collapsible containers in the sidebar. Note that the Create Page button in the sidebar is within a mini window div, so if you set a border on jot-miniWindow, you'll get a border around the Create Page button, which probably isn't what you want. You can set a border on each named mini window, but new mini windows added by plugins will not automatically have a border applied. To add a border to new mini windows in the sidebar, you'll need to name them and add a corresponding style to your style sheet.

#jot-oobeLink

Controls the display of the getting started link displayed in the sidebar on the WikiHome page.

#jot-sideData #jot-createPage

Controls the display of the create page button in the sidebar.

#jot-favs

Controls the display of the favorites miniWindow.

#jot-changes

Controls the display of the recent changes miniWindow.

#jot-invite

Controls the display of the invite miniWindow.

#jot-apps

Controls the display of the applications miniWindow.

Content

The content area contains the main page content. Elements within the content area include:

• Page name
• Breadcrumbs
• Version Information
• Page data
• Comments
• Attachments
• Edit buttons

The basic structure of the content looks liks this:

#jot-content

The content area can be positioned relative to the main div within the canvas. In the default layout, the content is displayed to the right of the sidebar.

#jot-editButtons-top

Contains the edit button displayed at the top of pages displayed in view mode, the save, view, and cancel buttons displayed in edit mode, and the save, edit again, and cancel buttons displayed in preview mode.

#jot-breadcrumbs

Contains the breadcrumbs displayed in view mode. No breadcrumbs are displayed on the WikiHome page. Note that the breadcrumb container is not included on the page when there are no breadcrumbs--there is no empty breadcrumb container that occupies the space.

#jot-pageName

Applied to the H1 header of the main content area that contains the page title.

#jot-versionInfo

#jot-page

The main body of the page. You can define sub-elements for anything that can be added to the page. However,
keep in mind that if you define custom styles for elements within the page container the WYSIWYG editor might
not preview your styles, which could be confusing to the user. (Because what they see is not what they get.)

#jot-relatedContent

Contains the comments and attachments displayed in view mode. You can define several basic styles for the contents
of the comments and attachments containers, including:

• Basic header style for the boxes: .jot-relatedContent h2
• UI devices for collapsing and expanding the content:
  • .jot-relatedContent.collapsed h2
  • .jot-relatedContent h2 a.jot-toggle
  • .jot-relatedContent.collapsed .jot-content

• A basic div for holding the content in a jot-relatedContent box: .jot-relatedContent .jot-content
• Special style for the comments/attachments count: .jot-relatedContent h2 .jot-count
• Basic style for any kind of container such as div or table: .jot-relatedContent .jot-item
• Footer styles:
  • .jot-relatedContent .jot-footer
  • .jot-relatedContent .jot-footer .jot-add

#jot-comments

A sub-element of #jot-relatedContent that contains the comment box. You can define several sub-elements for jot-comments, including:

• a.jot-add
• h2
• a.jot-toggle
• span.jot-count
• span.jot-commentCount
• div.jot-content
• span.jot-ajax-comments
• div#jot-comment-footer.jot-footer
• a
• form#jot-addComment
• div.jot-item.jot-comment
• input (type=text)

#jot-attachments

A sub-element of #jot-relatedContent that contains the attachments box. You can define several sub-elements for jot-attachments, including:

• h2
• a.jot-toggle
• span.jot-count
• span.jot-attachmentCount
• div.jot-content
• table#jot-attachmentsTable.jot-item
• thead
• tr
• td
• tbody#jot-attach-body
• tr#jot-addAttachmentRow
• td
• form
• input (type=text)
• label
• strong (has hard-coded style:color)
• input (type=file, which cannot be styled)
• input#jot-addAttachmentButton.jot-btn (type=submit)

#jot-editButtons-bottom

Contains the the save, view, and cancel buttons displayed in edit mode, and the save, edit again, and cancel buttons displayed in preview mode. (Not used in view mode.)

Footer

The footer contains a collection of navigation links (jot-footerNav), an extension area (jot-footerExtensions), links to general JotSpot information (jot-jotLinks), and the copyright (jot-copyright). The basic structure of the sidebar looks like this:

#jot-footer

The footer is independent of the canvas and can be positioned relative to the page body. In the default layout, the footer is displayed below the canvas and .jot-wrapper positions the footer content to line it up with the main content.

#jot-footerNav

Positions the columns of page action links. jot-footerNav h3 defines the
header style for the columns of page action links. The .jot-footerLinks div creates the illusion of table columns in the default layout. You can vary the number of columns and rows by changing the width. By un-floating them you could stack them, and by floating right you could reverse the order.

View Mode

Pages displayed in view mode use the .jot-view class. See Jot CSS Architecture for information about the elements displayed in view mode.

.jot-view

This is a special body class applied to pages displayed in view-mode. In the default layout, view displays the standard header, sidebar, main content, and footer elements.

Edit Mode

Pages viewed in edit mode use the .jot-edit class. Edit pages contain two main structural elements, jot-canvas and jot-footer. The canvas contains the jot-header, jot-loginInfo, and jot-main elements. The main element is an editMode form with a content element that includes jot-pageName, jot-editButtons (top and bottom), and jot-page elements. The form.editMode textarea elements controls the display of the editable text area.

.jot-edit

This is a special body class applied to pages viewed in edit-mode.In the default layout, edit page displays the standard header, a main content area that contains the editable text area and edit buttons, and the jotlinks and copyright footer elements.

form.editMode textarea

Controls the text area displayed in edit mode.

Preview Mode

Pages viewed in preview mode use the .jot-preview class. The structure of a preview page mirrors the edit page, except that page content appears as it will in view mode rather than as an editable textarea.

.jot-preview

This is a special body class applied to pages displayed in view-mode. In the default layout, preview displays the standard header, a main content area that contains the preview of the page conten, edit buttons, and the jotlinks and copyright footer elements.

Login Page

The login page contains the sign-in controls. It contains two main structural elements, jot-canvas and jot-footer. The canvas contains the a special jot-loginLogo element and the standard jot-main element with a single jot-content sub-element. The content element contains a special jot-login element. The footer contains the jot-footerExtensions, jot-jotLinks, and jot-copyright elements. The login page does not contain a standard jot-header element, the logo on the login page is contained within the jot-loginLogo div.

.jot-view-loginpage

This is a special body class applied to the login page. In the default layout, login page displays the standard JotSpot Wiki logo, a simple sign-in dialog, and a footer that contains jot-jotLinks and jot-copyright elements.

#jot-loginLogo

Login pages do not display a standard banner. Instead, there's a special jot-loginLogo element that's positioned relative to the canvas. This element contains the default logo.

Note: The logo on the login page is not a link, so you can't hide the default logo and set a background image on the link to display a custom logo.

System Pages

System pages like error messages use the .jot-view-systempage class. You can use descendent selectors to style these pages differently from normal pages.

.jot-view-systempage

This is a special body class applied to system pages.