When put into the header of a page and when running a mobile device, Viewporter will first try to scroll away any URL or debug bars to maximize the visible window, and then substracts the remaining chrome/UI height from the window, effectively removing ugly scrollbars along the way. It will also track orientationchange, thus, you will always have a maximized viewing experience.
In v1, all you had to to was to put Viewporter into the head of the page. There's just a little bit more to do in v2, but it isn't painful:
<meta name="viewport" content="initial-scale=1.0,maximum-scale=1.0" />
<body> <div id="viewporter"> ... </div> </body>
That's it, really! Feel free to have a look at the demo pages if something doesn't work as expected.
You could of course try to set the viewport meta tag yourselves, as suggested in various places, usually something like <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1">. You will quickly recognize two apparent issues:
- proportional device-height doesn't subtract the chrome height, so the window is always larger than the viewport when set, causing scrollbars even on empty pages
- rotating the device will cause the page to zoom (as device-width isn't inverted on rotation)
- even with a manually fixed viewport, there's a stupid gap at the bottom of the page (when using absolutely positioned elements)
So what's in it for you? There's a couple of automatic advantages for you when the Viewporter is running. Here's a list:
- Maximized viewport (scrolling away unneeded UI)
- Easy layouting
Yep. Take a <div>, position it absolutely, set its width and height to "50%", left and bottom to 0 and the background to any color. With Viewporter enabled, it will be placed at the bottom left corner of the window, and stretch to the middle of the window. Sounds obvious right? It isn't really, when you want a maximized window.
Viewporter is almost zero configuration. There's only one constant to check if Viewporter is in fact running, a convienience method to detect landscape orientation and a smart ready callback function. In addition, there's a couple of events you will likely want to use.
- viewporter.forceDetection (Boolean) - defaults to false, enabling it will cause the Viewporter not to use its profiles for devices (see devicepixel demo)
- viewporter.ACTIVE - true if the Viewporter is enabled and running (smartphones!), false if not (Desktop, non-touch device)
- viewporter.READY - true when the viewportready function has already been fired. Useful if you're lazy loading initializing code
- viewporter.isLandscape() - returns wether the device is rotated to landscape or not
- viewporter.ready() - accepts a callback and fires it when the viewporter has been successfully executed
All events fire as native events on the window object.
- viewportready - fires as soon as the Viewporter has been executed for the first time
- viewportchange - fires when the viewport changes, i.e. the device is rotated, and after Viewporter has been executed again