Portamento - easy sliding/floating panels in jQuery

Portamento is a jQuery plugin that makes it simple to add sliding (aka "floating") panel functionality to your web page. All that's needed is some simple CSS and one line of JavaScript, and you're away!

It works fine with floated and absolutely-positioned layouts, in all modern browsers and some not-so-modern ones too.

Portamento also has sensible behaviour if the user's viewport is too small to display the whole panel, so you don't need to worry about users not being able to see your important content.

Demos

In the Wild

Portamento is being used on real websites, right now. Take a look:

Croydon Creatives

Usage

Using Portamento is easy. Just follow the steps below and you'll have a smooth sliding panel in no time!

Include portamento.js in your page, just before </body>:

<script src="portamento.js"></script>
In your JavaScript, apply the plugin to the element you want to slide - in this case #example:

$('#example').portamento();

Portamento needs to be applied after the page has loaded, so it's best to put it in your $(document).ready() listener.
Do a bit of CSS. Portamento wraps your sliding panel in an element with the ID portamento_container. #portamento_container takes care of positioning your sliding panel correctly, to avoid any nasty jumping around. Set the panel to have position:absolute when it's in #portamento_container. The panel will have a class of fixed when it's sliding, so give that position:fixed. For example:
```
#portamento_container {
	float:right; 
	position:relative;
}

#portamento_container #example {
	float:none; 
	position:absolute;
}

#portamento_container #example.fixed {
	position:fixed;
}
```
This might look scary, but it's really quite simple. Check out the demo source for real-world examples.
Customize Portamento with any options you want:

$('#example').portamento({wrapper: $('#example_wrapper'), gap: 50});
Get sliding!

Options

You can customise Portamento with the following options:

wrapper - the element that you want to visually contain the sliding panel. The sliding panel won't go out of its wrapper's boundaries, and respects the wrapper's padding. The default wrapper is the document's <body>.

gap - the number of pixels to leave between the top of the viewport and the top of the sliding panel. The default value is 10.

disableWorkaround - disable the workaround for not-quite capable browsers. Some users will lose the sliding functionality, but the content will still be there.

The options all have sensible defaults, so in most cases you don't need to worry about them.

FAQ

What browsers will Portamento work with?

Anything that supports the CSS property position: fixed is classed as a fully-capable browser. That means IE7+, Firefox 3+, Safari 4+ (non-iOS), Chrome 4+, Opera 10+ and possibly earlier versions of everything except IE (quelle surprise!).
What happens to other browsers?

Not-quite-capable browsers (including iOS browsers and IE<7) are supported via a workaround - not quite as smooth, but preserves the functionality. The workaround can be disabled with the disableWorkaround option.
I get a JavaScript error: “wrapper.css("paddingTop") is undefined” or “Uncaught TypeError: Cannot call method 'replace' of undefined”.

This is most likely because you've included the Portamento <script> element in the document's <head> rather than at the end of the <body>. Try moving it down to just before the </body> and everything should be fine.
I can't get it working - I need help!

No worries - get in touch via comment, email or on Twitter and I'll do my best to help you out.
It's broken, you suck!

Yikes, sorry. Get in touch and I'll try to get it sorted. Or if you like, fork Portamento on Github and submit the fix yourself - you'll earn my eternal gratitude and a mention on this page, leading to fame and fortune (not guaranteed).
What license is Portamento released under?

Portamento is released under the GPLv3 and Apache 2.0 licenses - your choice. Basically this means you can do what you like with Portamento - modify it, incorporate it into a larger system etc; but even if you're using the Apache license please consider contributing back any improvements so we can all benefit. If you're not sure, get in touch and I'll be happy to help.
Portamento? WTF is that?

Portamento is the musical term for a note that slides smoothly between two pitches - geddit? You can read all about it on Wikipedia if you like.

Version History

1.1.1 - Changed licensing to include Apache 2.0.

1.1 - Fixed a bug where the panel would jump if your wrapper had top padding, fixed issues if your panel had top margin set, added event listener for device orientation change plus various code optimizations with thanks to Stephen Fulljames.

1.0.1 - fixed a bug caused by IE misreporting the document width. Thanks to Clive Walker for the report and verification!

1.0 - initial release.

Limitations / Roadmap

Currently you can only use Portamento for one element on the page. This should be fine for most people, but I'm working on multiple-element support.
Flash & Firefox: a bug currently found in Firefox will cause Flash embeds to reload upon any change to the position property of a parent element. In short, if you have Flash inside a panel, then add Portamento to that panel, the Flash will reload when the panel starts sliding. Hopefully this should be fixed before too long, but be aware. Thanks to Ryan Bridges for the heads-up.
Small viewports - because we're using position:fixed, Portamento won't slide your element if you have a horizontal scrollbar - that would just get messy. However, because of the way mobile browsers resize a page to fit their viewport, some of them will still report the viewport as being smaller than the document - so Portamento won't work in those cases. However, users on those devices won't notice anything amiss, as the panel will just stay in place.

Portamento.js