Documentation

Setting up TopUp for your website requires the least amount of effort. You have the choice of either hosting the javascript and images on your own webserver or you can just include the javascript with one line of code and that’s it! This has been made possible because TopUp injects the stylesheet code in the webpage. Choosing for the last option gives you the possibility of always being up-to-date with the latest features and bugfixes WITHOUT altering your code!

Table of Contents

Installation

When including from gettopup.com (the easiest setup)

Put the following in the head element:
<script type=”text/javascript” src=”https://gettopup.com/releases/latest/top_up-min.js”></script>

Note: You can configure TopUp (libs, fast mode, paths) in the querystring of the URL (read documentation)

( you can also include a specific release by replacing latest with the version e.g. 1.3.2 )

When hosting the Javascript and images yourself

Download and unpack the latest TopUp version
Copy the entire(!) jquery directory in the same directory as the TopUp Javascript file. TopUp will automatically determine which Javascript libraries (jQuery and/or jQuery UI) to include from the jquery directory when missing. Please note that TopUp will only include one(!) file to reduce the amount of HTTP requests! An include will look like this:
<script type=”text/javascript” src=”path/to/your/jquery/*.js”></script>
Copy the entire(!) images directory to the correct location. At default, TopUp assumes that the images reside at the same host as the file itself in the following path /images/top_up/. You can change the path (and even the host) by changing the variables TopUp.host and TopUp.images_path as the following:
<script type=”text/javascript”>
TopUp.host = “http://www.anotherwebsite.com/”;
TopUp.images_path = “assets/images/top_up/”;
</script>

Note: The proper place for Rails developers would be the application.js
Copy the entire(!) players directory to the correct location. At default, TopUp assumes that the players reside at the same host as the file itself in the following path /players/. You can change the path and host by changing the variables TopUp.host and TopUp.players_path as the following:
<script type=”text/javascript”>
TopUp.host = “http://www.anotherwebsite.com/”;
TopUp.players_path = “assets/players/”;
</script>

Note: The proper place for Rails developers would be the application.js
Now you start using TopUp on your webpages by putting the following in the head element:
<script type=”text/javascript” src=”path/to/your/top_up-min.js”></script>

Note: You can configure TopUp (libs, fast mode, paths) in the querystring of the URL (read documentation)

Remember: You can still use Prototype without having conflicts, just make sure you include TopUp first.

Configure TopUp with the query string

It is possible to configure TopUp without(!) typing a single line of Javascript code. How can this be done? By passing parameters in the query string of the TopUp library inclusion URL. You can configure the following:

which jQuery libraries to auto-include or not to auto-include libraries at all
whether to enable fast mode for better performance in IE
the variables TopUp.host, TopUp.images_path and TopUp.players_path

A few examples to configure TopUp:

libs  – Specify which jQuery libraries to auto-include or not to auto-include libraries at all:
Instruct TopUp not to auto-include any jQuery libraries at all

<script type=”text/javascript” src=”path/to/top_up-min.js?libs=”></script>

Instruct TopUp only to auto-include the jQuery Core library

<script type=”text/javascript” src=”path/to/top_up-min.js?libs=core”></script>

Instruct TopUp to auto-include the jQuery Core library and jQuery Effects Core & Clip library

<script type=”text/javascript” src=”path/to/top_up-min.js?libs=core+clip”></script>

Available libs:

(empty) – instruct TopUp not to auto-include any of the jQuery libraries at all
all     – include all the available libraries
core    – jQuery Core library (currently 1.4.2)
clip    – which enables using clip / switch effect
resize  – which enables resizing the TopUp dialog
fast_mode – Specify whether fast mode has to be enabled or not:
Instruct TopUp to enable fast mode

<script type=”text/javascript” src=”path/to/top_up-min.js?fast_mode=1″></script>
host, images_path, players_path – Override the default assets variables:
Alter the TopUp.images_path variable

<script type=”text/javascript” src=”path/to/top_up-min.js?images_path=/foo”></script>
And as usual with URL query string parameters, you can combine them using ‘&’:
Instruct TopUp only to auto-include the jQuery Core library and to enable fast mode

<script type=”text/javascript” src=”path/to/top_up-min.js?libs=core&fast;_mode=1″></script>

Setting up link elements

You can accomplish this in 3 ways:

By adding the class top_up to the link:
<a href=”/images/photos/1.jpg” class=”top_up”>
<img src=”/images/thumbnails/1.jpg”/>
</a>

Note: TopUp will appear in the default preset
By specifying TopUp options in the toptions attribute of the link:
<a href=”/images/photos/1.jpg” toptions=”shaded = 1, overlayClose = 1″>
<img src=”/images/thumbnails/1.jpg”/>
</a>

Note: Adding the class top_up is not required anymore
By specifying TopUp preset(s). Presets make it possible to assign certain toptions for a specific group of elements. Such a group is identified using the well-known CSS selector. Using TopUp presets keeps your HTML code clean and keeps it simple. The following shows an example of specifying toptions for (1) links within the element with the id images and (2) for elements with the class shaded:
<script type=”text/javascript”>
TopUp.addPresets({
“#images a”: {
group: “images”,
layout: “quicklook”,
modal: 0
},
“.shaded”: {
shaded: 1
}
});
</script>

Note: The proper place for Rails developers would be the application.js

Available toptions

As mentioned earlier, you can pass options to TopUp by using either the attribute toptions or by specifying a TopUp preset. This is an overview of the possible toptions you can pass. Most of them are self describing.

Name	Default	Description
topUp	auto	This is the element which will be referred to as the TopUp element / trigger. Usually a link with either the class top_up, the attribute toptions or TopUp preset which matches the link. This will automatically be derived by the TopUp module when clicked. Options: CSS selector string
type	auto	By specifying the type, you can instruct TopUp how to load and display the reference content. At default the type is auto-determined based on the extension of the reference. Options: ‘image’, ‘flash’, ‘flashvideo’, ‘quicktime’, ‘realplayer’, ‘windowsmedia’, ‘iframe’, ‘html’, ‘dom’, ‘ajax’, ‘script’
post	0	If set to 1, TopUp will use the POST method for Ajax request. This requires the type to be either ‘ajax’ or ‘script’. Options: 0 or 1
storeCurrent	0	If set to 1, TopUp will store the currently displayed content. Call TopUp.restore() to restore the stored content. Options: 0 or 1
parameters	”	This will be send as extra parameters for the Ajax request. This requires the type to be either ‘ajax’ or ‘script’. Options: String
title	”	Title of the TopUp window. Options: String
readAltText	0	If set to 1, TopUp will use the img alt (alternative) text as title, when present of course. Please note that the title toption will be overridden by the alt text. There is a way to pre and/or postfix the alt text though, TopUp will gsub ‘{alt}’ in the title toption with the alt text (e.g. ‘Gallery {alt}’ will be ‘Gallery Photo 3’). Options: 0 or 1
layout	‘dashboard’	Layout in which the TopUp will appear. Options: ‘dashboard’, ‘quicklook’, ‘flatlook’
width	auto	Width of the content in pixels. Options: Integer
height	auto	Height of the content in pixels. Options: Integer
x	auto	The x-position of the TopUp dialog in pixels. Options: Integer
y	auto	The y-position of the TopUp dialog in pixels. Options: Integer
effect	‘transform’	Effect of how the TopUp will show and hide. Options: ‘transform’, ‘appear’ (alias is ‘fade’), ‘switch’ (alias is ‘clip’), ‘show’ (alias is ‘hide’)
modal	0	If set to 1, the TopUp window will be modal which means that you cannot click outside the TopUp window. Options: 0 or 1
shaded	0	If set to 1, a shaded overlay will be displayed behind the TopUp window. This also makes the TopUp modal. Options: 0 or 1
overlayClose	0	If set to 1, the TopUp will close when. Options: 0 or 1
resizable	1	If set to 1, the TopUp will be resizable by dragging the right bottom corner of the TopUp window. Forced to 0 when displaying movie content. Options: 0 or 1
group	0	This makes it possible to group certain TopUp links. You can navigate through the group by clicking on the navigation arrows or by using the arrow keys. Options: String
noGroup	0	This overrides the displayed TopUp of being part of a group. Usefull when a link matches a preset with a group, but when you don’t want to display the group. Options: 0 or 1
ondisplay		This will be called after the TopUp dialog is opened or updated. Options: When calling TopUp.display() or TopUp.displayTopUp() a function, when specified as a toption the body of the function (e.g. toptions=”ondisplay = alert(‘Hi!’)”)
onclose		This will be called after the TopUp dialog is closed. Options: When calling TopUp.display() or TopUp.displayTopUp() a function, when specified as a toption the body of the function (e.g. toptions=”onclose = alert(‘Bye!’)”)

Just call your friend TopUp!

Eventually, all the TopUp actions are initiated by function calls to the TopUp Javascript module. Adding the top_up class, the toptions attribute or specifying TopUp presets only tells TopUp to bind the click event of the elements to a wrapper function in the TopUp module that there upon calls the core function to display TopUp. Aside from TopUp.display(), the TopUp module also has several other functions to communicate.

Name	Description
TopUp.defaultPreset(set)	You can change the default preset (set of toptions) by passing a toptions hash.
TopUp.addPresets(sets)	You can add extra presets (set of toptions) by passing a (nested) hash in which you specify toptions to elements which match to the specified CSS selector.
TopUp.ready(func)	You can pass functions to the TopUp module which will be called when the page is finished loading.
TopUp.displayTopUp(element, opts)	This is the wrapper function for TopUp.display() which is called when you click on a TopUp element.
TopUp.display(reference, opts)	This is the core function which shows the TopUp.
TopUp.enableFastMode(value)	Calling this enables (or disables) the TopUp fastmode which ignores coptions (when enabled) in order to improve performance. This is recommended for IE6 and IE7. Value is optional: 1) fastMode will be enabled when the value is undefined, 2) value can be a function which returns (fastMode = ) true of false, 3) value can be true or false.
TopUp.restore(storeCurrent, func)	Calling this restores the stored content. You can pass a callback function which will be called when the content is restored.
TopUp.update(func)	Calling this enables you to update the currently displayed content in the TopUp dialog. The ‘this’ reference inside the function is the jQuery element of the content container. For an example, please click on the inline DOM example on the homepage.
TopUp.previous()	Displays the previous entry within the group current. If there is no current group, nothing will happen.
TopUp.next()	Displays the next entry within the group current. If there is no current group, nothing will happen.
TopUp.overlayClose()	Closes the TopUp when visible and the current toptions include overlayClose is 1.
TopUp.close(callback)	Closes the TopUp when visible.