Kwix Manual

Overview

Kwix is a plugin for RapidWeaver. It allows you to build a new type of web page into your RapidWeaver web site. Kwix pages display a dynamic, animated menu of links with slick graphics and text that is matched to your site's theme.

Kwix uses industry-standard xHTML, CSS, and Javascript. But because you're using RapidWeaver, you don't need to know any of those things. All you need is a few minutes to select a few images, choose a nice style, and type in your menu titles. In minutes you can have a slick, Web 2.0 addition to your site.

Kwix is designed to work directly with Blocks so that you can combine Kwix with other elements to create beautiful and unique interfaces.

Getting Started

Adding a Kwix Page

To add a Kwix page to your RapidWeaver site, click the '''+''' button in the lower left of the RapidWeaver window. The Add Page sheet drops down and shows you the types of pages that you can add. Choose Kwix from the list and then click the Add button.

Building a Kwix

Adding Kwix Items

To add a new item to your Kwix:
1. Click the + button in the lower left of the Kwix edit area. This adds a new, untitled Kwix item to the list of items in the Kwix edit area.
2. Customize the new Kwix item by editing the content on the right side of the Kwix edit area. Each of the following sections describes a customizable component of Kwix.

Icon

To choose an icon for your Kwix item:
1. Select the Kwix item in the list.
2. Click the Icons button to open the Kwix Icons pallette. The Kwix Icons pallette shows all of the installed Kwix icons.
3. Click on an icon to choose it for your Kwix item.
Alternatively, you can drag any image file into the Kwix Icon image well. Kwix does not do any processing on the icon images, so make sure that your image is already the size that you want.
You can download and add more icons to the Icon Window. See Choosing Icons for more details.

Title

To add a title to your Kwix, type it into the Title field. Most Kwix styles don't have too much room for large titles, so it's best to keep things short and sweet. The title is placed into your Kwix in the H3 size defined by your theme. Some themes have a large font and others a small font. Test your site's theme to see how it appears.

Subtitle

If you'd like your Kwix item to have a bit more text, add a subtitle. Most themes display this in a slightly smaller font, the body text font, so there's a bit more room for text than in the Title.

Note: If you add more than one line of text, keep in mind that web browsers cannot hyphenate words when the line wraps. So, longer words are prone to get cut off

Link

To add a link to your Kwix item, click the orange Link button. The standard RapidWeaver link edit sheet drops down in which you add the link.

Organizing Your items

To organize the items in your Kwix, drag and drop them to arrange them into the order that you'd like.

Removing Items

To remove a Kwix item, click on it and then click on the - button in the lower left of the Kwix edit area.

Using Icons

Choosing an Icon

To choose an icon for your Kwix item, select the Kwix item in the list and then click the Icons button. The Kwix Icons pallette shows all of the installed Kwix icons. Click on an icon in the window to choose a new icon for you Kwix item.

Adding Your Own Icon

To add your own icon to a Kwix item, drag and drop any image file into the Kwix Icon image well. Kwix uses this image as the icon for the selected Kwix item.
Kwix does not do any processing on the icon images, so make sure that your image is already the size that you want.

Styling your Kwix

There are several ways to to configure your Kwix. Although Kwix can be configured by hand and many details adjusted, if you want to use the same configuration on more than one Kwix page in your site, you need to use styles. You can use pre-made styles that were created by a designer, or you can create your own styles. Styles are stored in Kwix style files so they're easy to download and share.

Choosing a Style

To choose a style:
1. Click on the Setup button in the lower right corner of the Kwix Edit area.
2. Choose the Styles tab. The Inspector pallete shows each of the styles installed in Kwix. Kwix comes with a default style, but you can download more or create your own.
3. Click on the style's icon to select it.
4. Click the Apply button.

Note: If the Apply button is not displayed at the bottom of the inspector pallete, then that style is already selected for that Kwix.

Getting More Info About Styles

To see more information about a particular style, click on the style's icon and then click the Details disclosure triangle. The Inspector palette shows more information about the selected style including the author, the file name, and the author's comments.
If you'd like to see the style's file in the Finder, click on the -> arrow next to the File Name field. The Finder opens a window and selects the file that contains the style.

Getting More Styles

You can download more styles from the YourHead website here. To install your newly downloaded style, decompress the file (if your web browser didn't do it while it was downloading), make sure the Style tab is selected in the Inspector pallete, then drag and drop the file onto the Inspector pallete. The style is immediately available in Kwix.

Creating New Styles

If you've made some customizations to any setting in Kwix, you can save those settings as a style. To save a new Kwix style:
1. Click on the Setup button in the lower right corner of the Kwix Edit area.
2. Choose the Styles tab.
3. Click the + button in the lower left corner of the palette. This creates a new, untitled style for your settings. Open the Details disclosure triangle and customize the Title, Author, File Name, and Comments.
Although Kwix will build a default icon for your style, you can add your own by pasting it into the Style Details image well. Any changes you make to the Style Details are automatically saved to the style file.

Sharing Styles

Once you've created a style, you may want to share it with friends or on the RapidWeaver forums. To share a style, simply share the style file. To locate a style file in the Finder:
1. Click on the Setup button in the lower right corner of the Kwix Edit area.
2. Choose the Styles tab.
3. Click on the style's icon to select it.
4. Click the Details disclosure triangle.
5. Clicking on the -> arrow next to the File Name field. The Finder comes to the front and shows the style file selected.

You can share this file with anyone; it's all they need to add the style to their own Kwix.

Note: It's good practice to compress the style in a zip file before sharing it. To do this in the Finder, Command-Click (or right-click) on the file and choose Compress "file name" from the pop-up menu. A new, compressed version of the file is created. Share the compressed copy.

Creating Backgrounds

Although Kwix comes with a nice default background, you can easily create your own custom background images and add them to you Kwix. Background images can be in nearly any format, but do take care in creating them so that they look nice when used in Kwix.

Overview

Before getting down to the details of designing an image, it's good to understand how Kwix uses the image to create the flexible background. The first thing to note is that each background image has three sizes: large, medium, and small. The large size is the image that is displayed when users mouseover a Kwix item. The medium size is the image that is displayed by default, when there is no interaction with the Kwix. The small size is the image that is displayed when another Kwix item is displaying its large image.

Designing Your Image

The most important thing to understand when designing a background image is how Kwix contracts and expands the image to display the large, medium, and small sizes. Kwix does not actually resize the image at all; that would be too CPU intensive for a web browser and would ruin the image quality. Instead you specify how much of the right side of the image to keep intact (via the Edge Width setting; see Modifying the Layout for more info), and Kwix makes a slice in the image at that point. When Kwix contracts the background image (to medium or small), the part of the image to the left of the slice is cropped (from its right edge) until the background is slim enough (depending on whether it needs to create a medium or small size). Then the cropped image and the right edge are joined to make the desired background image size.
The image is never expanded past its original dimensions. The original image is the (large) background when users mouseover a Kwix item.
The second most important thing to understand is that your original background image (the large size) determines how much space there is for text. If you take the large size background image and subtract the area of the medium size image, that is the amount of space left for text in the large size. It is important to create images that are wide enough to have reasonable room for text but not so wide that the large size is too wide. A good place to start is editing the default images that came with Kwix. After you master working with those images, your own experimentation with sizes and shapes should come easily.

Size

Although each background image is only a single size, there are three sizes to keep in mind when designing a nice image: large, medium, and small. To achieve the most usable background image, your image should look good when contracted to its small size and look natural at its medium size, which should be about halfway between large and small. A good starting point is an original image that is about 250px wide by about 175px tall. It should look okay when contracted to roughly 75-100px wide for its small size and about 175px for its medium size.
All background images in a set MUST be the same size. If images are different sizes, then background image corruption will occur.

The Edge

When a Kwix item contracts and the right edge moves left, there is a delineated boundary between the two parts of the image. If the background is a simple solid fill color, this edge is not be noticeable. But if the background has a horizontal color gradient (from left to right), then there is a good chance that when the Kwix item contracts the background will not look very nice.
The best way to get the best looking background is to keep the horizontal variability of the image to a minimum. Create gradients that vary top to bottom and stay away from patterns or image backgrounds. Some patterns that have a degree of randomness may look okay when in the contracted state, so experimentation is probably a wise choice.

Adding Background Images

You need to add any background images that you create to Kwix. To add a background image to Kwix:
1. Click on the Setup button in the lower right corner of the Kwix Edit area.
2. Choose the Backgrounds tab.
3. If you want to delete an unused background image, select the background that you want to delete and click the - button.
4. Now drag your new background images (all at once or one at a time) from the Finder into the list of backgrounds. This create new background items from all of your images.
Now that all of your backgrounds are in Kwix, reorder them by dragging them around the list. The background at the top of the list is used for your first Kwix item; the second one in the list is used for your second Kwix, and so on. If there are more backgrounds than Kwix items, that's okay. Kwix uses only as many backgrounds as needed. If there are more Kwix items than background images, then once Kwix uses the whole list it will start from the beginning again. You do need at least one background image for Kwix to function properly.

Creating a Style From Your Backgrounds

Now that you have all of your background images in Kwix and organized just the way you would like, you can save this configuration as a Kwix style. A Kwix style is available to all of your Kwix pages and can even be shared with friends or on the RapidWeaver forum. See the Styling Your Kwix section for more details about how to save and share a style.

Modifying the Layout

Kwix Width

The Kwix Width setting changes the total width of the entire Kwix. If your Kwix doesn't quite have enough overlap to show as much text as you'd like, reducing the Kwix width may be a good solution.
When you use Kwix along with Blocks the Kwix width is the width that your Page Block should be. A Kwix will never be wider than the this value.

Edge Width

The Edge Width changes the width of the right edge that moves leftward when the Kwix contracts and expands. To understand how to use this you may want to read the section on designing backgrounds.

Text Inset Margin

The Text Inset Margin setting changes how much space there is from the edge of the background image to the placement of the text area of the Kwix.
Note: If your text is displayed on the left side of the Kwix item then the right margin setting controls the margin to the middle overlap point. And vice versa for if you text is displayed on the Right side.

Speed

The speed slider controls the speed of the animation.

Text Position

The Text Position setting controls where the Title and Subtitle text appears. You an also completely disable the titles.

Image Position

The image Position controls where the Icon will be placed. It will always be vertically centered and depending on the setting will be centered horizontally centered within the area that it's placed.

Building with Blocks

Kwix provides a nice, clean menu, but not much else. If you want to add more content to your Kwix page then you should have a look at Blocks. Even with the free Blocks demo you can have 4 blocks of content. Enough for your Kwix menu and three blocks of text that can be placed anywhere else. If you have purchased the full version of Blocks you can combine other page content, lots of images, and of course, your Kwix menu.
Before you get going, make sure you have a recent version of Blocks. Blocks 3.1 and later are compatible with Kwix.

Adding a Kwix Page Block

To add a Kwix menu to a Blocks layout you must first build a complete Kwix. Once done you'll need two pieces of info about your Kwix to bring it into Blocks. (1) You'll need the Kwix Width setting from the Settings window under the Layout tab and (2) you'll need to know how tall the images of the background are. Both can be found by a bit of experimentation, though, so don't worry too much if you find that info hard to acquire.
Next, add a Page Block to your Blocks layout by clicking on the Page Block tool. A Page Block imports the content from other pages on your site into your Blocks layout.
Double click on the new Page Block to configure it, this will open the Blocks Inspector to the Page Block-Content tab. Select the name of your Kwix page from the popup menu.
Still in the Blocks inspector open the Block section to the Layout tab. Set the Width and Height settings to the height and width of your Kwix.

Adding more Kwix

You can add many Kwix menus to a page. Of course the more dynamic content you add to a page, the slower everything will run, but a few Kwix should not be very taxing to a web browser.
To add more than one Kwix you'll need a separate page and a separate Page Block for each Kwix. You cannot add the same Kwix to the same page more than once. Doing so will break at least one of the Kwix scripts.

Adding other content

Once you've added a Kwix you can add other content to your Blocks page like text, Images, and content from other pages.

Troubleshooting

The Preview Doesn't Show a Kwix at All

The most likely cause of this problem is that you don't have a RapidWeaver 3.6 compatible theme. You can test this by switching to one of the default themes in RapidWeaver. If that solves the problems then your original theme is likely not RW3.6 compatible. Solution: Use a RapidWeaver 3.6 compatible theme, ask your theme designer for an update, or make the fix yourself. To fix add the %plugin_header% tag to your theme just before the end of the head section of the index.html file.

The Kwix looks OK, but doesn't work.

This can be caused by a number of Javascript errors. Usually this is caused by mixing Kwix with some other Javscript content or a theme that uses Javascript. Kwix uses MooTools v1.1. It is not compatible with other Javascript base libraries such as Prototype, Sciptaculous, or earlier versions of MooTools or Moo.fx. JQuery has a compatibility mode that can work with base libraries like MooTools, you'll have to experiment to see if that compatibility mode is being used. Solution: Remove the offending Javascript, switch themes, or switch to a compatibility mode if your base library supports one.

The Kwix barely moves

If there is not a lot of overlap of the Kwix items then there is not much room for them to move. Solution: Create more overlap by reducing the Kwix Width setting or by increasing the width of your Background images.

The fonts my theme uses don't work well for Kwix

Kwix uses the fonts from your theme. It uses the Header-3 font for the main title and body text for the subtitle. If you'd like change the font the best thing to do is to change your theme or override the themes font. That requires a bit of CSS coding either within the theme, or you can add it just to the page in the CSS section of the Page Inspector window.
The CSS in question can be done as follows.

To override the properties of the subtitle:

.kwix-text {
your css here
}

To override the properties of the title:

.kwix-text h3 {
your css here
}

The title override should always come last.