SplitView for JQuery Mobile
If you’ve worked with an iPad for any significant period of time, odds are you’ve run across one of its main user interfaces, ‘Split View’, which is a type of master-detail interface. An example version of this interface on an iPad is shown below:
In a master-detail interface, the left side of the screen displays a list of selectable items while the right side displays the details of the item selected. In actuality, implementations of this type of interface are commonplace in both web and native applications. That being said, in this post, I want to talk a bit about the core building blocks used in the building of this type of interface for a less common use case, mobile web applications, specifically by leveraging JQuery Mobile.
Developers who have worked with web applications for any significant period of time have likely used or dabbled with JQuery and will thus find many familiarities in JQuery Mobile, JQuery’s mobile offering, which just this past month released version 1.0 of its mobile framework. Just like with the JQuery infrastructure, JQuery Mobile has a plugin ecosystem, and one of the more promising plugins is the ‘SplitView’ plugin, providing an HTML5 version of the ‘Split View’ interface. The code for this plugin is contained within the ‘experiments/splitview’ fork of JQuery Mobile found here. When looking for split view support within JQuery Mobile, and specifically looking for the best replication of a UI similar to the one used on the JQuery Mobile documentation site, the ‘SplitView’ plugin seems to be the best current option. As is noted in the plugin’s documentation, the core JQuery Mobile team assisted in the development of the splitview plugin, helping lend credence to its value. Studying the structure of the plugin’s demo and the structure of the JQuery Mobile demos site, one can see that both SplitView implementations share much in common.
As the plugin’s documentation notes, it works with any device’s browser – desktop, tables, and mobile phones. Some of the nice features which I think help give it a leg-up on other solutions include support for landscape and portrait orientations, and use of JQuery Mobile experimental ‘momentum’ scrolling (contained separately in the same ‘experiments’ folder of the JQuery Mobile fork referenced below).
In my opinion, the best way to get going with the code is to work with it locally, so I recommend cloning the forked JQuery Mobile repository. Simply ensure that you have git installed locally (good, simple instructions for installing git for various OS’s can be found here) and clone the fork repository, via:
git clone https://github.com/asyraf9/jquery-mobile.git
The index.html page under the aforementioned experiments/splitview fork is unfortunately not quite up to par. Not only does it not use the latest JQuery libraries (mobile and core), it’s layout does not match the expected split-view look found on the splitview plugin site. To fix this, the simplest approach I found was to copy the ‘body’ section of the html source from the plugin’s site into your local version and additionally referencing locally the same versions of JQuery Mobile CSS and JS files that that site references (by pulling down said files). I personally had limited success with the absolute latest CSS and JS JQuery Mobile files, so unless you need those features, for testing at least it might be simplest to use the same version as those that are proven to work best.
After making these local changes to ensure a working local copy, one is encouraged to look a bit deeper at many of the key components and concepts used in building the pages that make up a SplitView-based interface. Here’s a roadmap for you:
The Left Panel:
A snapshot of the html for a slimmed down left panel of a master-detail interface, taken from the SplitView plugin site, is shown below (*if you do not see a code snippet here please reload the page, as the Gist script does not always immediately load unfortunately):
which visually looks like:
You’ll notice that the top-level div:
has the inline css style:
Width: 25%; min-width: 250px
This does exactly what you might imagine – it confines the panel to 25% of the screen, with a min-width of 250px. But how does the ‘left’ panel stay on the left of the page? Of course, it’s the ui-panel-left –changing it to right indeed moves the panel to the right of the page. And the ui-border-right creates the bold line that acts to ‘split’ the left panel from the rest of the page.
Nested under the top level div can be any set of elements, but with a SplitView one would expect some combination of lists and headers, and our expectations are met here with a header div and a content div, which contains the separate list elements. As will be discussed in a moment, these sections contain data-roles that we would expect as well – “header”, “content”, and “listview”. On that note…
Below is a breakdown of some of the custom data attributes used in the sample left-panel:
Data-hash -> Possible values: true, false, crumbs. Defines whether a panel’s page transition should be tracked in history or not. The ‘crumbs’ setting changes the panel’s back button into a button that points to the previous page and disable JQuery Mobile from tracking the panel’s history
Data-id -> Used by JQuery Mobile framework to ensure global navigation elements stay in the sample place between transitions. SplitView uses ‘main’ as the ‘id’ of the right-hand panel and ‘menu’ as the ‘id’ of the left-hand panel.
Data-url -> Used to identify a page – intended to be linked to by other components of other “pages”, which may or may not require a page load, depending on whether pages are pre-fetched, to reduce additional server calls (typically for static content)
Data-role -> Arguably the most important part of a JQuery Mobile application, it tells JQuery Mobile how to render a particular piece of HTML content. Example values include header, footer, page, and listview. When set to ‘page’, everything with the ‘div’ with the page data-role will be treated as a separate page or screen.
Data-backbtn -> Possible values: true, false: When true generates the back button on every ‘page’ to let you get back to where you navigated from.
Data-icon -> Adds an image to a button. Example button code: and more are defined here.
Another significant item of note is that several elements from the example split-view components leverage the data-theme element. Themes a-e are provided in JQuery Mobile‘s default styling, thus making f-z available to plugins and other developers. It is standard practice to add ‘-x’ where x is the theme letter for classes that are themed implementations of JQuery stylings (i.e., ui-btn-up-b, ui-btn-up-c, etc). . The SplitView demo site uses the ‘g’ theme. One could take the example code snippets or the html from the entire split-view and change classes that end in –g and change it to a, b, c, etc. to see how other out-of-the-box themes impact the UI. That being said, the ui-* classes you see in the SplitView sample are from JQuery UI, which has custom styles defined for these elements in the various JQuery Mobile css files linked to from the source code.
The right panels are really quite simple in their basic form – let’s take a look at an example page:
That’s it! Note some of the corollary to components discussed from the left-panel. The ‘bar’ div id for one – this gets linked to by one of our ‘list’ elements that make up the ‘listview’ from the left-panel. The data-backbtn value of false will ensure that in the ‘header’ section of this page that a navigation element will not show to take the user back to the previous page they were viewing when they clicked a ‘bar’ listview link. Finally, note the data-panel is defined as ‘main’, which defines where this new page should load (remember, ‘main’ was right hand panel, ‘menu’, left).
One other item to note is that several elements on the split view, including each list item on the left panel, and the ‘Main’ and ‘Demos’ buttons, leverage JQuery Mobile data-transitions for object and page-change events. A succinct discussion of how to define these transitions for JQuery Mobile pages can be found here. In short, adding a ‘data-transition’ element with 1 of the 6 currently supported transition names gives that element said transition. So note that not only can one set what page they want to load in the ‘main’ panel, but they could (and often should) define how the transition to show that view would/should occur.
With more focus being given by organizations to “Mobile First” strategies, to “Responsive Design”, and HTML5 mobile web applications that work across devices, JQuery Mobile SplitView is a good tool to have in your arsenal to build what of late has been one of the main native tablet interfaces into your mobile web application. I believe leveraging components from SplitView in JQuery Mobile’s own documentation site acts as a demonstration that the interface has value in mobile web applications, and can be performant and powerful. Give it a try, and let me know what you think or what issues/questions you have in the comments!