Multiview

Welcome to the Demo!

JQM changes

the following changes have been made to JQM to make the plugin work

Main Section

Load some content here...

Setup

Setup

Create a normal JQM page and add the trigger element data-wrapper="true" to the page. This will fire the plugin when the page loads. If your app has several independent JQM pages (no multipage), make sure to include the plugin script, css plus the modified JQM file on every page!

The page above will be your wrapper-page. Header and Footer in this page will your global header/footer.

Any popover panels you want to add will go after the content section of this page. If you want to create a multipage or splitscreen page, remove the content section and just put panels inside the wrapper. See the demos for details

Panel

Panels need to be div tags. To specify a panel you need to add the following attributes:

  • data-role="panel" - indicating this is a panel
  • data-id="your_panel_name" - a unique name to differentiate panels
  • data-panel="type" - can bei either popover, menu, main, fullwidth
  • data-hash="history/crumbs" (optional) - whether the panel should have an active history alongside JQM and browser
  • data-autoshow="once" (optional) - whether to show the panel the first time this page is loaded to the DOM

Panels itself can contain any number of nested JQM pages. All headers/footers in these pages will be local (can be fixed, too). Make sure to include a data-show="first" attribute to the default page for each panel. Otherwise the panel will be black when it's opened or a page loads.

Panel Navigation

The plugin tweaks JQM navigation. The main differences are:

  • $.mobile.pageContainer - allows page container to be changed to either body or panels
  • data-target="panel-id" - needs to be attached to every panel-link. Omitting this will break the layout as JQM will take over
  • pageContainer: $(panel-id) - needs to be included, when calling panel transitions programmatically

Layouts

Use the plugin to create the following layouts:

Popover Panels

popLayout

For plain popover panels in regular JQM pages, just insert the panels after the content section. The popovers can contain any number of JQM pages, which you can navigate in between.

More info

Fullwidth Panels

fwLayout

To create a loadable multipage, just replace the wrapper page's content section with a fullwidth panel using data-panel="fullwidth" and put your nested "multipage" pages inside. JQM will always load the wrapper page thereby also pulling in all of the pages nested in the fullwidth panel.

More info

Splitview Panels

splitLayout

To create a two column layout, just replace the wrapper page with two panels, one with data-panel="main", the other with data-panel="menu". Put all your nested pages inside either panel. These pages will also be loaded alongside the wrapper page. More info

Combinations

combo

You can mix background panels (main/menu/fullwidth) and popover panels as you want. So you could have a main/menu layout with several popovers or regular JQM pages with popovers. Large apps with several independent JQM and plugin pages are also possible, so there should be no limit in what to create.

More info

Popover Panels

Popover panels can be used on normal JQM pages and panel pages alike. The basics of the popover are set by the .ui-popover class, while size and position of the popover can be set individually (demo uses .ui-popover1, .ui-popver2

popLayout

A few things to be beware of when setting up a popover:

  • popovers need to be behave like fixed headers or footers in order to "stay on screen" = be repositioned when scrolling.
  • therefore assign either .ui-element-fixed-top or .ui-element-fixed-bottom to the popover
  • this will make the popover behave like fixed header/footer and be repositioned when scrolling stops
  • you can add a class of .ui-triangle-top or .ui-triangle-bottom for small indicator triangles
  • to place a popover exactly center screen, just add a class of .ui-popover-center
  • specifying data-autoshow="once" on the panel will show the it once when the page is added to the DOM (login window)
  • specifying data-hash="history" will add this panel to the plugin history enableing back/fwd button on browser/mobile
  • specifying data-hash="crumbs" will also add back button on every page (currently both history/crumbs are avtive!)

Some rules for popovers:

  • Only one popover can be open at a time! If you had 5 popovers open, which one do you show on a smartphone as page in view?
  • Whenever a popover closes, it's history is reset. As long as it is open, it's history always supercedes all other panels and JQM
Popover Demo

Multipage Layouts

If you use a fullwidth background panel, you can set up your loadable multipage layout. Just drop all nested pages inside the fullwidth panel and don't forget to link using data-target="your_panel_id". Since the panel is inside a single wrapper page, this will be loaded by JQM along with all nested pages. As a bonus, specifying header or footer outside of the panel makes them global across all pages. Dropping them inside on nested pages makes them local.

popLayout

A few things to be beware of when setting up a fullwidth panel:

  • global header/footer are outside of the panel, local header/footers are inside nested pages
  • specifying data-hash="history" will add this panel to the plugin history enableing back/fwd button on browser/mobile
  • specifying data-hash="crumbs" will also add back button on every page (currently both history/crumbs are avtive!)
Fullwidth Panel Demo

Splitview Layouts

To setup a splitview layout, just replace the content section with two panels, main and menu. Like in a fullwidth setup, any header/footer dropped inside the wrapper page but outside of the panels will be your global header/footer across all nested pages, while headers/footers inside nested pages will be local.

popLayout

A few things to be beware of when setting up a main/menu panel:

  • global header/footer are outside of the panels, local header/footers are inside nested pages
  • menu width and min-width are settable options menuWidth and menuMinWidth
  • below a settable threshold width, the menu will change to a popover with a toggle button. This is called popover-mode vs. splitview-mode
  • by specifying the option switchable: true, the menu can also be toggled in splitview-mode
  • the switchable also provides changeable switchableIcon and switchableHideOnLoad options to further modify the button
  • by default the menu button will be placed on the main panel header. If there is a button present (back-btn...) it will be merged into a controlgroup
  • if you want the menu button to be placed somewhere else, assign .ui-menu-button-flex to the designated element. The menu button will be dropped there.
  • specifying data-hash="history" will add this panel to the plugin history enableing back/fwd button on browser/mobile
  • specifying data-hash="crumbs" will also add back button on every page (currently both history/crumbs are avtive!)

Some rules for menu/main panels:

  • Panel CSS mimics the body-CSS (position: static, dimensions matching screen). Don't mess with it...
  • As panels are static, nested pages by default are 100% screen width. This plugin tweaks the page width according to screen-mode. So don't overwrite page-CSS thinking panel-CSS is enough. In Menu/Main setups it's not...
Menu/Main Panel Demo

Mixed Layouts

You can mix background panels with popovers as you like, so a menu/main layout with one or more popovers is no problem at all. You can also mix splitview pages together with regular JQM pages to create larger web apps. The plugin always works across the DOM, so you can add a lot of complexity to apps with little effort.

comboLayout

A few things to be beware of when setting up a main/menu panel:

  • if you do apps across multiple pages, make sure the plugin is on every page, so whereever you start, the plugin also initiates.
Combo Panel Demo

Screen Modes

The plugin offers three layout modes, which are running automatically:

Fullscreen Mode

fullscreen-mode

Fullscreen mode fires below a threshold width (settable option). In Fullscreen mode all panels become fullscreen pages, so if you opened a popover, it will open like regular JQM page with "back-button".

More info

Popover Mode

popover-mode

Another threshold switches between popover and splitview mode. In Popover mode, menu panels will change into popovers, so the screen is reserved for the main content.

More info

Splitview Mode

splitview-mode

In splitview mode, main and menu sit side by side. Per default an orientationchange will switch the layout from splitview to popover mode.

More info

Fullscreen mode

Currently fullscreen mode fires if screen width is less than 320px. Below this threshold, all popovers loose class .ui-popover, which drops all formatting (borders,etc.). New class ui-fullscreen overwrites all dimensions to 100% and positions the popover absolute (vs. static) in other screen modes.

demo_fullsceen

A few things to be beware in fullscreen mode:

  • think of popover panel pages as regular pages in fullscreen mode
  • adding class .iconposSwitcher-a or .iconposSwitcher-div to buttons or controlgroups drops the button text in fullscreen mode. Saves space.
  • when popovers are openend their regular "close" button now becomes a "back" button
  • fullscreen mode also fires when available screen height is smaller than the height of any popover panel on the page. Think of your smartphone in landscape mode
  • to check out fullscreen mode, just go to any demo, shrink the screen and reload the page
Load Demo Section

Popover mode

Popover mode fires above 320px and below 768px or in portrait mode. If you are using a menu/main layout the menu will be hidden and changed into a regular popover, which can be toggled using a menu toggle button.

demo_popover

A few things to be beware in popover mode:

  • By default the popover toggle button is in the header top left. If there is already a button, both will be merged into a controlgroup
  • You can relocate the menu toggle button by assigning class .ui-menu-button-flex to the element that should hold the button (think of a listview filter with editable options in the menu
  • On small screen sizes the popover menu will turn into a fullscreen page, just like regular popover panels in fullscreen-mode
Load Demo Section

Splitview mode

In Landscape mode or above screen width of 768px, splitview mode fires enabling menu und main panels to sit side by side.

demo_splitview

A few things to be beware in splitview mode:

  • You can hide/show the menu if you specify the option switchable:true when calling the plugin. This also adds the menu toggle button in splitview mode
  • The menu width variies between 25% and 250px in the default settings. This requires the width and margin-left of the main panel and nested pages to be modified on resize, which is currently turned off
Load Demo Section

Features Modes

Please select a feature from the menu!

Adaptive Layouts

The plugin adapts uses different modes to change the layout depending on "available space". Especially if multiple panels are used, this requires some contraints to be able to have a clean navigation across different size devices.

adaptive layout

To see how this works, load any of the layout demos, resize the screen and refresh, change orientation or load the page on a mobile device.

  • TODO:
  • supersize-mode (above ????px width) for webTV with increased button padding, no vertical scrolling etc)
  • make all thresholds option-able
  • fine tuning

Global Toolbars

Since the plugin sits inside a regular JQM wrapper page and only the content is changing, the plugin offers global header and footer by default. Both can be ommitted or replaced with local header/footers sitting inside each page.

Use any of the below demo pages to check out the different header/footer options

  • TODO:
  • still flickering
  • still jumping up on first load, if content/page is smaller than available height

Fixed Elements Top/Bottom

fixed elements

Fixed Elements share the behavior of fixed headers/footers. They are necessary to allow popover panels to also be repositioned after scrolling down a page. Otherwise they would be stuck where originally positioned. To "fix" any element just add a class of ui-element-fixed-top or .ui-element-fixed-bottom to this element. This will fix them to the top or bottom of the screen. To position use margin, and left/right only, because top/bottom values are needed for positioning of the element itself.

Use any of the below demo pages to check out how fixed elements reposition when scrolling

  • TODO:
  • fine-tuning
  • allow scrolltops, which are currently disabled, when loading an external page into a popover-panel (causes fixed bottom panel to jump up)

Context Page Loading

Context loading allows to load a page in one panel and fire another transition in another panel. To use the context-loader simply add two more attributes to a link. data-context="pageID" is denotes the context page to be loaded and data-context-panel="panelID" indicates into which panel this page should go.

Check the below demo page to see how context loading works.

  • TODO:
  • only works from menu to main panel, all other transitions have a messed up event orders, thereby partially blanking a page
Context Loading

Load external pages into Panels

Loading external pages into any panel is tricky, because a lot of stuff changes in JQM, which potentially breaks the plugin. Currently loading pages into a panel more or less works. Panel history and deeplinking need finetuning.

Click the link below to load an empty combo layout which adds all pages on click.

  • TODO:
  • URL breaking sometimes, panel history still messy, deeplinking not working
External Page

Panel History

The plugin comes with it's own history routine which can be acitvated for each panel by assinging either data-hash="history" or data-hash="crumbs". Currently both are firing together and register every panel transition, so clicking crumbs back-buttons or the browser back button allows to navigate back through the multiview page. To make this work, every panel gets a history stack which is set at the initially displayed page. On every transition the stack is increased by a single entry (page ID). Menu and main panel always increase together, with the passive increase getting an entry named "yield". When the user clicks a back button the plugin checks all panels if a) a popover is open (always goes down first, as they close and reset when the user leaves them) and b) which panel has the highest stack. This way popover are returned back to base, after that, main/menu/fullwidth panel and once all panels are back at base level, JQM takes over again.

Click the link below to see this in action

  • TODO:
  • still terrible, context not in sync, external page loading messes up everything
  • needs work
  • need to separate hash and history to make them separate options to use
Panel History

Autoshow Popovers

Popovers can be shown by specifying data-autoshow="once" on the panel. This attribute triggers a panel toggle when the page loaded and is removed afterwards.

Click the link below to see this in action

Autoshow

Toggle Menus

To hide/show a menu in splitview mode (same as in popover mode), the option: switchable: true has to be added to the plugin call. Additional options also include, which icon to use for the menu toggle button switchableIcon:'icon' and whether to show the menu panel when the page is loaded switchableHideOnLoad:true.

Click the link below to see this in action

Toggle Menu

Demos

Click any of the buttons to load a new page with the respective DEMO into the DOM.

Script

Some changes have been made to JQM to make the plugin work. Most of this could probably be relocated to inside the plugin. The plugin itself also has some sections of duplicate code, where JQM stuff wasn't accessible from outside.

Core Utilities

JQM 1.0

JQM 1.0.multiview

need to add a check for wrapper or panels, otherwise it's not possible to load nested pages in externally loaded wrapper pages. this makes the navigation work

Transitionpage - scrollTop

JQM 1.0

JQM 1.0.multiview

Block scrollTop if not in fullscreen mode and page transition is inside a popover, otherwise popover panel jump up. This should be removed if possible.

JQM 1.0

JQM 1.0.multiview

if fromPage is an internal page it's a panel transition, so the pagehide event has to be blocked to avoid dropping the wrapper page. This also catches external panel pages, which have been loaded into the DOM and should be removed when navigation away from them unless data-dom-cache is set.

Transitionhandler (css3 and default)

JQM 1.0

JQM 1.0.multiview

Not perfect yet: determine when to drop only the active page class and when to drop the active page class and the wrapper page class. This is tricky...

changePage

JQM 1.0

JQM 1.0.multiview

Add page container as option, set to body on JQM transitions, check for targetPanel specified (data-target=) and re-route to plugin in case a target panel is set.

handleHashChange

JQM 1.0

JQM 1.0.multiview

Needs work: Re-route to panel history routine if panels on the page with data-hash="history" set. If wrapper page is external-page and panel-history is active, I cannot leave the wrapper and go back to the page visited before going to the wrapper, unless it's done like this

pushState

JQM 1.0

JQM 1.0.multiview

(a) if the wrapper is first in the DOM, need to add #id to exisiting URL, (b) if wrapper is loaded as external page, need to overwrite initial URL with new page URL. remove pushStateFlag, which is only set on panel transitions, this ensures pushStateFlag is emptied every time a new page is added to the DOM, so on the next panel transition, it can be reset (or overwritten)

fixed Toolbars

JQM 1.0

JQM 1.0.multiview

This has changed quite a bit to incorporate global header/footer as well as fixed elements top and bottom

plugin init

JQM 1.0

JQM 1.0.multiview

make sure the loader is always appended to the body and not any other page container