TopBox

By Will Woodgate ~ www.themeflood.com

Introduction
TopBox is a new modal (popup) window
effect developed from scratch specifically
for RapidWeaver. The idea of TopBox is to
provide a basic modal window which
overcomes some of the frustrating
problems other mainstream lightboxes
suffer from. TopBox supports a wide
variety content types and works perfectly
with the @import function in PlusKit,
enabling you to import content from
several other page types like contact
forms, slideshows, stacks, video content,
tables, PDF’s, tab boxes etc. Simply put,
TopBox was developed by a RapidWeaver
user, for RapidWeaver users.

When developing TopBox, one of the

primary goals was to create a simple and
lightweight modal window effect. Something which is easy of end users to setup and offering a high
degree of customisability. The code used by TopBox has been kept to a minimum, so TopBox won’t
slow down pages or add considerable bandwidth to projects.

TopBox also boasts excellent compatibility with new devices such as the iPhone and iPad. Previously
this is something many mainstream modal window plugins have failed to achieve, and are probably
unlikely to in the short term. TopBox can work with all of these devices, together with regular desktop
web browsers.

Key features of TopBox

• Full cross-browser compatibility with all major web browsers (no hacks or conditional comments)
• Simple fade in / fade out toggle effect powered by jQuery 1.4
• TopBox triggers are formed of REL attributes, so any link in a page can be 'TopBoxed'
• Minimal, valid code results in instantaneous popups and low bandwidth
• Embedded files and content are preloaded to limit display delays
• TopBoxes and window shades are fully customisable using built in colour and opacity controls
• Supports the @import function in PlusKit and a wide variety of content types
• Content in a TopBox is still machine-readable and is SEO friendly
• Compatible with the iPhone, iPod Touch and the iPad
• Option for a close button in the TopBox using a separate Stack (TopBox Closer)
Cross browser compatibility
Many, many hours have been spent ensuring TopBox is
compatible with a wide selection of modern web
browsers. It is understood how important this is for
professional web developers using RapidWeaver. Even
though no browser hacks or conditional comments are used in the TopBox code, you can still expect to
see full compatibility with all of these major web browsers on different platforms:

• Internet Explorer 6, Internet Explorer 7, Internet Explorer 8

• Firefox 3.6, Firefox 4
• Safari 4, Safari 5
• Chrome
• Maxthon
• Lunnerscape
• Opera 10.5
• Flock

Ultimately, some areas of browser compatibility are dependant on the type of content you are using in
TopBox. For example, some older web browsers may not support certain formats of video and newer
devices like the iPad do not feature Flash support. Likewise, search engines will still be able to read your
TopBox content and index it for improved search results.

System requirements
You will need to be running the latest version of RapidWeaver - preferably version 4.0 or later. The Stack
version is only compatible with Stacks 1.3. If you are using an older version of stacks, you should
consider upgrading.

Compatibility with themes varies. TopBox was tested with all the standard stock themes supplied with
RapidWeaver and a selection of popular third-party themes as well. But bare in mind that the quality and
age of third-party themes varies somewhat and there could be undiscovered problems. It is impossible
to test against every theme and other factors. For this reason, it is highly recommended you download
and test the free trial version of TopBox to check it works in your project, before purchasing a full copy.
Themes which have a heavy reliance on layer-effects, scroll boxes, or frames are unlikely to work
particularly well. Additionally, themes with special Javascript effects powered by libraries such as
MooTools, Prototype, Glow or Scriptalicious may also present problems in a form of code conflicts with
jQuery.

TopBox is a basic modal window effect...

With this in mind, it would be unwise to compare the capabilities of TopBox with other effects like
MediaBox Advanced, SlimBox, FancyBox or ShadowBox to name but a few. TopBox is specifically
designed to be small, lightweight, easy to use and agile. This simply means that advanced features like
customisable skins, support for image sets, pagination and automatic resizing of images etc. falls
outside of the TopBox remit. There may be workaround solutions for some of these in TopBox.
TopBox Setup & Configuration

30 second setup guide

After downloading TopBox, double-click the topbox.stack file icon to install. Restart RapidWeaver if it is
already open. In edit mode on your Stacks page, drag a TopBox stack and drop it into your page. Drag
and drop a second stack (e.g. a text or image stack) onto the indicated TopBox placeholder:

Somewhere on your Stacks page, create a new link. In the link setup window in RapidWeaver, set the
URL to ‘#’. Add a new custom attribute, typing ‘rel’ in the name field and ‘topbox1’ in the value field like
this:

Click ‘Set Link’ to finish and preview your page in RapidWeaver. This link will act as the trigger to open
your TopBox when the link is clicked. That’s all there is to it.
Configuring your TopBox
Using the default settings, TopBox works great. But you may wish to add more than one TopBox stack
to a page, or make some style changes to the shade opacity, shade colour, TopBox position or TopBox
width. Fortunately all this can be done in the TopBox HUD (inspector) quite easily. Switch your Stacks
page back to edit mode, single click the TopBox Stack in the page and then click the circular ‘i’ icon to
open the inspector, pictured below:

• Trigger REL is the name of the REL attribute you use to trigger an individual TopBox. This should
be different to other TopBoxes on the same page, a simple word or number, lowercase without any
spaces. A link with a matching REL attribute will trigger this TopBox.

• TopBox Width enables you to change the width of your TopBox. Use any unit of measurement
you prefer such as pixels, em’s or percent. Don’t forget to type in the unit of measurement.

• TopBox Height can normally be left at ‘auto’ unless you want a fixed height TopBox with
scrollbars. Again you can use any unit of measurement to apply a fixed height.

• Fade In Speed controls the speed at which the TopBox and window shade fade into view when
triggered. This is specified in milliseconds (ms). Higher values indicate slower animations. You can
also type ‘fast’ or ‘slow’ keywords in the box (including quotes), for durations of 200 or 600
milliseconds respectively.

• Fade Out Speed is similar to the fade in speed settings, but control the speed at which the
TopBox and window shade fade out. Again, higher values indicate slower animations. You can also
type ‘fast’ or ‘slow’ keywords in the box (including quotes), for durations of 200 or 600
milliseconds respectively.

• Shade Opacity is a slider which changes the window shade transparency between 0% (fully
transparent) and 99% (almost no transparency).

• Shade Color enables you to change the window shade background colour using a simple colour
picker. You can choose any colour you like to match an existing colour scheme or to add some
creativity flare.
Customising TopBox with CSS
TopBox is wonderfully easy to customise, particularly if you are already familiar with the basics of CSS
code. In essence, TopBox has one single CSS selector which can be used to hook on your own custom
styles:

.topBox {

You can apply basic styling like borders and various text formatting like this:

.topBox {
! border: 2px solid #cccccc;
! font-style: italic;
! font-size: 150%;
! background-color: #eaeaea !important;
}

TopBox will already apply some basic formatting by default like a white background colour. This can be
overridden by including an !important declaration in the code, as shown above. If you are not too
concerned about Internet Explorer support, you can dive into some more advanced styling, like rounded
corners and box shadows which look fantastic:

.topBox {
! -moz-border-radius: 20px;
! -webkit-border-radius: 20px;
! border-radius: 20px;
! -moz-box-shadow: 10px 10px 5px #000;
! -webkit-box-shadow: 10px 10px 5px #000;
! box-shadow: 10px 10px 5px #000;
}

These CSS3 properties work great in modern browsers like Safari, Firefox, Opera and Chrome. In non
CSS3-compliant web browsers, CSS3 code will be safely ignored and these special effects wont be
applied. Any custom CSS code you use can be entered under the page inspector. Some third-party
themes also contain a custom.css file where your code can be entered. Custom CSS code you use will
be applied to all TopBoxes on the same page (if you are using multiple TopBoxes).

If you are using the TopBox stack, remember that when you drag and drop a stack into TopBox, you
also have access to a second set of styles. For example, if you add a text stack, opening the text stack
settings gives you access to border, background, margin and padding settings. All of these can be
utilised to improve the appearance of your TopBoxes, without requiring any code.

It is impossible to explain all there is to know about CSS code. If you are new to CSS or need to refresh
your knowledge, there are plenty of useful resources available online free of charge.
TopBox Closer Stack

Adding a close button to your TopBox

TopBox does not include a conventional
‘close’ button in the open modal window.
The reason being simply that users
demand different styles of close button
and want the ability to easily customise
buttons or text themselves to suit projects
or localisation's. Then there are those who
would rather have TopBox running as it is,
without the hinderance from a close
button - particularly true for those using
TopBox to display a confirmation dialogue
or contact form.

Rather than building the option for a

button into the main TopBox stack, the
choice was taken to create a separate
stack. This is referred to as the TopBox
Closer Stack and is bundled with the main
TopBox stack. The main purpose of this
stack is to display a close button which
will act as a third TopBox close trigger.
This button can either be formed of text or an image and can be customised with CSS, to add borders,
colours background and test styling. Keeping the two stacks separate seems to work better and offer
more solutions for customising the close button.

After you have added your TopBox stack, drag and drop a Close TopBox stack inside (so that it is
nested within the main TopBox). By default, the word ‘close’ is displayed as plain text in the top right
corner. This is basically what you should see in your main TopBox placeholder:
TopBox closer configuration
After opening the TopBox Closer HUD (inspector) you have options to customise various aspects. Firstly,
you can change normal Stack settings like the padding, margin or borders. Moving down, you have
settings specific to the TopBox Closer Stack, as pictured below:

• Vertical is a field which requires the use of a keyword - either ‘top’ or ‘bottom’ (without the quote
marks). This will display your close button at either the top or bottom of a TopBox

• Vertical (px) enables you to push the button up to 20px away from either the top or bottom of the
TopBox. It gives you more precise positioning

• Horizontal can be used to place the close button on either the left or right of the TopBox. Again you
will need to use either ‘left’ or ‘right’ keywords (without the quote marks)

• Horizontal (px) enables you to push the button up to 20px away from either the left or right of the
TopBox edge. It gives you more precise positioning

• Button is the actual text or image displayed as a close button. You can either use a simple keyword
like ‘Close’, a single ‘X’ or an image. To use an image button, publish the button online and then use
the standard HTML code for an image.
<img src=“http://www.example.com/button.jpg” alt=“Close” />

Important - All fields in the TopBox Closer HUD must contain a value. Note how position keywords are
entered in lowercase with no spacing. In effect, the positioning settings emulate absolute-positioning in
standard CSS code. You do not need to enter colons or semi-colons in the keywords - this is done for
you by the Stack.

The close button gets positioned absolutely within the open TopBox. This means that larger buttons may
partially obscure underlying content. In some instances, this effect may be welcomed. But if you do not
want buttons to overlay TopBox content, this can be resolved by increasing padding and or margins.

If using image buttons, it is recommended these are saved in a web-safe file format (e.g. GIF, PNG or
JPG). If possible, try to optimise these images for the internet, to keep file sizes to a minimum. Only use
images or icons which you have created yourself or have permission to reuse.
Customising the close button with CSS
On its own, the close button looks very dull and insignificant. CSS code can be used to style the close
button and improve its appearance. In theory there is just one single CSS selector name to use which is
called topBoxClose:

.topBoxClose {
!
}

Almost any CSS code can be applied to this button. Custom CSS code can either go in the Page
Inspector within RapidWeaver, or your theme may contain a dedicated custom.css file to paste CSS
code into. Feel free to copy an paste any of the code examples below to get started.

To begin with, it may be good to start by customising the static button using this code:

.topBoxClose {
! width: 65px;
! line-height: 1.50em;
! background: #0c5585;
! color: #ffffff;
! border: 2px solid #cccccc;
! text-align: center;
! font-size: 125%;
! cursor: pointer;
}

Here we give the button a fixed width, a flexible (line) height, background fill, change text colour to white,
apply a border, change alignment to center, increase the font size and change the cursor style. Note the
use of hexadecimal colour values in the code. Also Americanised spelling is used, rather than traditional
English for words like ‘colour’ and ‘centre’.

Equally, the button can have it’s style changed when a user hovers a mouse cursor over it:

.topBoxClose:hover {
! background: #787f00;
! border: 2px solid #333333;
}

The code is similar to the first snippet, but we add a :hover pseudo class to the selector name, in order
to target the button hover behaviour. In this example, the body background colour and border colour are
changed. This makes the button look and behave a lot more like a button, even though it is not a true
link. Unfortunately :hover pseudo classes are not supported in Internet Explorer 6, without the aid of
extra javascript code. But in all other browsers, the :hover pseudo class works as expected. Internet
Explorer 6 support can probably be safely ignored in this instance, as we’re only dealing with minor
styling when someone hovers on a button.
TopBox Usage Notes

The technicalities of how TopBox works

While it’s certainly not essential to know the details of how TopBox works, some users may be interested
nonetheless. If you are just starting to experiment with your own jQuery code, I welcome you to check
out the source code and get an idea of how it works.

Much of the functionality in TopBox is achieved using jQuery Javascript. The process starts by
appending the TopBox container and window shade to the <body> tag in a page. Appending containers
enables TopBox to break outside of the stack and page containers, which in turn fixes many Internet
Explorer z-index and positioning bugs. This also improves compatibility with various RapidWeaver
themes. Very similar to Extra Content, TopBox automatically appends content into the TopBox container
at the top.

TopBox listens for a link with

a matching REL attribute to
be clicked. During this idle
period, TopBox preloads
content and performs some
calculations of window sizes
to prepare the window
shade and centre the
TopBox.

When the link with a

matching REL attribute is
clicked, the TopBox trigger
occurs. TopBox fades in
both the window shade and
TopBox container
simultaneously, to form the
modal effect. At this point,
TopBox stops running and
listens for a close trigger.
Clicking on the window
shade or pressing ESC is
the close trigger for TopBox,
both the window shade and TopBox container get faded out again.

Although the whole process sounds like quite a long chain of events, in theory there is some tolerance
within the order of events. An A - Z of instructions is stored in the browser DOM, so a web browser
knows what to do, without stalling or having to re-read the code each time. Its very clever stuff really,
even if you don't fully understand the whole process from start to finish. Naturally Javascript libraries like
jQuery do a lot of the heavy-horse stuff behind the scenes and bridge the browser bugs, so even expert
developers don't need to know all the finite details.
Using CSS to improve TopBox compatibility
TopBox works fine with basic
forms of content. But
sometimes you may wish to
try the use of some more
complex plugins or scripts.
Some may work without any
problem, others may not work.
Sometimes if the problem is a
Javascript code issue, a
solution is not easily found.
But if a problem is CSS
related, often this is something
which can be fixed. As an
example of the sort of things
which might go wrong,
layering may be incorrect,
items may run outside of a
TopBox or positioning may
change.

The first thing to do is to make

sure the script you are having difficulty with is the latest version available. Sometimes developers will
release updates to fix code errors or other bugs. Inadvertently, these updates may yield instant
improvements to TopBox compatibility. If updates are not available, you may need to preview your page
in Safari, and use the inspector to analyse the code (pictured above).

The sort of thing you are looking for in the inspector is CSS which is being overridden by something
else. Commonly overridden styles are shown with a line through them. If lots of styles are being
overridden, this might be where the stylesheet is breaking down and becoming buggy.

Study the code carefully and look for selector names. In the example shown here, the Image Caption
stack was not working in TopBox. It becomes apparent that the code being used to provide the caption
box dimensions is being cancelled out, so no caption was being shown on the image.

Selector names can be extracted from the inspector and used to create a custom stylesheet like this:

#imageCaptionBoxstacks_in_61_page4 {
! z-index: 9999;
! width: 800px !important;
! left: 0px !important;
}

The !important declaration is used to make this the definitive CSS code. In the above code example, the
z-index was increased, a manual width of 800px is specified and the caption is told to align left.
Combined, this small code fix makes the Image Caption Stack 100% compatible with TopBox.
Remember that if you edit or move your stacks, the ID numbers change - ultimately this will effect your
CSS selector names.
TopBox performance
In theory, there is no limit to
the number of TopBoxes you
can have running on the same
page. The code for each
TopBox amounts to only a few
kilobytes and all TopBoxes
have individual ID’s applied to
them automatically to prevent
conflicts.

Generally speaking, simple

HTML inline content like text,
images, forms and video
works best in TopBox.
Although you can incorporate
some more complicated
scripts like tab boxes and
slideshows, these may reduce
the performance of TopBox. In
particular, you may find that
TopBox content gets
displayed while the page is still
loading. In some instances, such issues may be very minor, but in other instances the performance
issues may be significantly worse. As every TopBox setup will be unique, it is best to approach more
adventurous TopBox integrations with a degree of caution.

Known issues
There are a few minor issues to be aware of when using TopBox:

• TopBox content may briefly flash as a page is loading. This is no different to the same issue when
using Extra Content in themes, but is worth mentioning nonetheless. The problem is more prominent
on Internet Explorer which has an older Javascript framework. Fade in and fade out animations may
also be a bit choppy compared with other, more modern web browsers.

• IE6 has weak support for CSS and does not understand fixed positioning. Therefore open TopBoxes
will be displayed at the top of a page, and a user on IE6 may need to scroll up to see the content. As
IE6 usage is so low now outside the corporate world, this shouldn’t be much of an issue. IE7 and IE8
have perfect support for TopBox.

• When opening a TopBox on the iPhone, iPod Touch or iPad, the page will be scrolled back to the top.
Because these handheld devices do not support fixed positioning of elements, this scrolling function
will ensure a TopBox always gets displayed in view. This may change if Apple updates the Safari
browser in future on these devices to support fixed elements.

• When testing TopBox in RapidWeaver using the escape (ESC) key to close a TopBox, this will trigger a
Mac OS X alert sound. When run in normal web browsers, no audible alert sound is played.
User pre-requirements
It is assumed that users of TopBox have a basic understanding of RapidWeaver and Stacks, including
installing new Stacks, setting up Stack pages, configuring stacks via the HUD, saving a project and
publishing it online. If you are new to Stacks or RapidWeaver, it is recommended you do some
background research and work through some introductory tutorials beforehand. This will help you get
the most from plugins such as TopBox and enable you to overcome basic obstacles, in turn putting you
on the right path to creating stunning web projects.

Getting support
This documentation contains a step-by-step guide covering all the basics of TopBox. If you encounter
problems using TopBox or have any general questions, please get in contact via the ThemeFlood
website or post a question to the Stacks section on the RapidWeaver forums.

If you are encountering particular problems with a certain Stack, plugin or theme, this should be raised
with the developer of that particular product. If he or she is unable to help, post your query to the
RapidWeaver forums or consider using another product which may work better. It is impossible to draw
up a definitive list of compatible themes or plugins for use with TopBox. Equally it is difficult to provide
guidance or support on untested themes and plugins. There are bound to be things which don’t work as
intended it you are doing more unusual things with TopBox.

EULA (End User License) agreement

Your use of TopBox is subject to the following EULA (End User License Agreement):

You may...
- Use purchased products for personal and commercial projects
- Modify and customise products to meet your own requirements
- Make backup copies of products (providing backups are not redistributed)
- Promote your use of products in site showcases
- Request free updates as and when updates are available
- Install products on computers owned by yourself

You may not...

- Redistribute or transfer products in part or whole
- Use in conjunction with explicit, illegal or offensive material
- Claim the product to be your own design or work
- Resell products in part or whole or claim false affiliation
- Convert products to use in other applications or on other platforms
- Remove copyright marks or credits which may be present

THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.