SimpleSplitView

About SimpleSplitView

SimpleSplitView is pretty much exactly what it sounds like: A very simple jQuery plugin that provides an iPad-style split view for mobile devices wide enough to support it. For browsers with a horizontal resolution of 700 or fewer pixels, the plugin renders the two sides as subsequent pages. It works great in conjunction with jQuery Mobile, although it is not technically required.

Unlike other split view implementations for jQuery Mobile, SimpleSplitView does not fork the jQuery Mobile project.

SimpleSplitView is open source software and you are free to use it in commercial projects as long as the copyright header is left intact. It was originally written by Peter Yared and Marc Raiser, and is currently maintained by Newbound, Inc.

Usage

It's easy to add SimpleSplitView to any jQuery project. Just include the JavaScript file in your web page and you can turn any div into a split view container by adding the splitviewcontainer class to it and invoking the simplesplitview() function on it. If you are using jQuery Mobile, the div should be the content div of a jQuery Mobile page and you should make your call to simplesplitview() after the page has been loaded.

<head>
	...
	<script type='text/javascript' src='SimpleSplitView.js'></script>
	<script type='text/javascript'>
		$('#PAGEID').live('pageshow', function(event) { // Necessary for jQuery Mobile
			$('#CONTAINERID').simplesplitview();
		});
	</script>
	...
</head>

NOTE: Replace PAGEID with the id of the jQuery Mobile page div id and CONTAINERID with the id of the div within that page which should contain the split view.

Panels

When you invoke simplesplitview() on a div, the SimpleSplitView plugin rearranges the contents of that div into a table with two columns and a line between them which form the left and right panels of the split view. The split view container must be a member of the class "splitviewcontainer". If you are using jQuery Mobile, the div should be the content div of a jQuery Mobile page. You can define any number of div tags to display in either the left or right panel by assigning the 'leftside' or 'rightside' class respectively to direct children of the container div. The first div of each class will be the ones visible when the page loads.

<div data-role='page' id='mainpage' data-title='SimpleSplitView' data-theme='a'>
	<div data-role='content' id='splitviewcontainer' class='splitviewcontainer'>
		<div class='leftside' id='leftpanel1'>
			<h2>Left Panel 1</h2>
			...
		</div>
		<div class='leftside' id='leftpanel2'>
			<h2>Left Panel 2</h2>
			...
		</div>
		<div class='rightside' id='rightpanel1'>
			<h2>Right Panel 1</h2>
			...
		</div>
		<div class='rightside' id='rightpanel2'>
			<h2>Right Panel 2</h2>
			...
		</div>
		<span>This will be discarded</span>
	</div>
</div>

NOTE: Any direct children of the container div that are not members of either the "leftside" or "rightside" class will be discarded by the SimpleSplitView plugin at runtime.

Navigation

In order to avoid forking the jQuery Mobile project, the split view contents are not defined as jQuery Mobile pages, opting instead to use classes to define "leftside" and "rightside" views. Unfortunately, this means you cannot simply hyperlink to them in order to switch from one view to another.

There are four navigational functions supported by SimpleSplitView: showLeft, showRight, navBack and navHome. SimpleSplitView uses the traditional jQuery plugin syntax for the navigational methods it supports, which is essentially the same as the initialization call but with additional paramters. For example:

$('#CONTAINERID').simplesplitview('showRight', 'RIGHTDIVID');

Functions:

Method	Description	Arguments
showLeft	Display a 'leftside' view. Optional parameters specify a default "rightside" view, and allow the suppression of the transition animation for the right and left sides. The rightdiv parameter is ignored when not in split view mode.	leftdiv, [rightdiv], [dontscrollright], [dontscrollleft]
showRight	Display a 'rightside' view. Optional parameter allows the suppression of the transition animation.	rightdiv, [dontscroll]
navBack	Navigate to the previous view.	none
navHome	Navigate to the default startup view.	none

Invoking:

Typically you will want to define shortcut function calls to invoke the plugin functions. For example:

function showLeft(leftdiv, rightdiv, dontscrollright, dontscrollleft) {
	$('#CONTAINERID').simplesplitview('showLeft', leftdiv, rightdiv, dontscrollright, dontscrollleft);
}

function showRight(rightdiv, dontscroll) {
	$('#CONTAINERID').simplesplitview('showRight', rightdiv, dontscroll);
}

function navHome() {
	$('#CONTAINERID').simplesplitview('navHome');
}

function navBack() {
	$('#CONTAINERID').simplesplitview('navBack');
}

This will allow for simple linking in your HTML:

<a onclick="showLeft('leftpanel2', 'rightpanel2');">Panel 2</a>

Buttons

In order to get "back" and "home" buttons that are only visible after navigating away from the default startup view, you must give each button an id that is a variation on the container's id: Specifically, the container's id plus either "_backbutton" or "_homebutton". For example:

<div data-role='header' data-position='fixed' data-theme='a'>
	<a onclick='navBack();' data-icon='back' style='display: none;' id='CONTAINERID_backbutton'>Back</a>
	<h1 id='appmaintitle'>SimpleSplitView</h1>
	<a onclick='navHome();' data-icon='home' style='display: none;' id='CONTAINERID_homebutton'>Home</a>
</div>

Download

CURRENT VERSION: 1.0.1
RELEASE DATE: March 21, 2012

simplesplitview-1.0.js
Example HTML (this page)

License

SimpleSplitView is open source software and you are free to use it in commercial projects as long as the copyright header is left intact. SimpleSplitView is released under the same licensing terms as jQuery and jQuery Mobile, which means you may use it under the terms of either the MIT License or the GNU General Public License (GPL) Version 2.