panel.xml

<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="../entries2html.xsl" ?>
<entry name="panel" namespace="fn" type="widget" widgetnamespace="mobile" event-prefix="panel" init-selector=":jqmData(role=&#39;panel&#39;)">
	<title>Panel Widget</title>
	<desc>Creates a panel widget</desc>
	<longdesc>
		<p>Panels are designed to be as flexible as possible to make it easy to create menus, collapsible columns, drawers, inspectors panes and more.
		<iframe src="/resources/panel/example1.html" style="width:100%;height:440px;border:0px"></iframe>
		</p>
		<h3>Where panel markup goes in a page</h3>

		<p>A panel must be a sibling to the header, content, and footer elements inside a jQuery Mobile page. You can add the panel markup either <em>before</em> or <em>after</em> these elements, but not in between.</p>

		<p>Here is an example of the panel before the header, content and footer in the source order:</p>

<pre><code><![CDATA[
<div data-role="page">

	<div data-role="panel" id="mypanel">
		<!-- panel content goes here -->
	</div><!-- /panel -->

	<!-- header -->
	<!-- content -->
	<!-- footer -->

</div><!-- page -->
]]></code></pre>

		<p>Alternately, it's possible to add the panel markup <em>after</em> the header, content and footer in the source order, just before the end of the page container. Where in the source order you place the panel markup will depend on how you want to page content to read for people experiencing the page in a C-grade device (HTML only) or for a screen reader.</p>

		<p>If a page contains a panel the framework wraps the header, content and footer sections in a <code>div</code>. When opening a panel with display mode "reveal" or "push" the transition is applied to this wrapper. An exception is fixed headers and footers. Those are not included in the wrapper, but will transition in sync with it. Be aware of the fact that all your visible page content should live inside those page sections.</p>

		<h4>CSS Multi-column Layout</h4>
		<p>To avoid blinks when opening a panel, we force hardware acceleration on WebKit browsers. The CSS that is used to do this can cause issues with buttons and form elements on the page if their container has a CSS multi-column layout (<code>column-count</code>). To resolve this you have to set the following rule for the element or its container:</p>

<pre><code><![CDATA[
-webkit-transform: translate3d( 0, 0, 0 );
]]></code></pre>

		<h3>External Panels</h3>
		<p>Since jQuery Mobile 1.4.0, it is also possible to have external panels. This means that you can now have panels located outside the page. Panels outside of a page must be initalized manually and will not be handled by auto init. Panels outside of pages will remain in the DOM (unless manually removed) as long as you use Ajax navigation, and can be opened or closed from any page. This can be handy when you want to use the same panel on more than one page. </p>

		<p>Here is an example of an external panel:</p>

<pre><code><![CDATA[
<div data-role="page">
	<!-- header -->
	<!-- content -->
	<!-- footer -->
</div><!-- page -->

<div data-role="panel" id="mypanel">
	<!-- panel content goes here -->
</div><!-- /panel -->
]]></code></pre>

		<p>The panel can be enhanced manually as follows:</p>

<pre><code><![CDATA[
$( function() {
	$( "#mypanel" ).panel();
} );
]]></code></pre>

		<p>Note that if the panel contains other jQuery Mobile widgets, such as listviews, these will need to be enhanced manually as well.</p>

		<h3>Panel markup conventions</h3>
		<p>A panel consists of a container with a <code><![CDATA[data-role="panel"]]></code> attribute and a unique <code>ID</code>. This <code>ID</code> will be referenced by the link or button to open and close the panel. The most basic panel markup looks like this:</p>

<pre><code><![CDATA[
<div data-role="panel" id="mypanel">
	<!-- panel content goes here -->
</div>
]]></code></pre>

		<p>The <strong>position</strong> of the panel on the screen is set by the <code>data-position</code> attribute. The position defaults to <code>left</code>, meaning it will appear from the left edge of the screen. Specify <code>data-position="right"</code> for it to appear from the right edge instead.</p>

		<p>The <strong>display mode</strong> of the panel is set by the <code>data-display</code> attribute. The defaults to <code>reveal</code>, meaning the panel will sit under the page and reveal as the page slides away. Specify <code>data-display="overlay"</code> for the panel to appear on top of the page contents. A third mode, <code>data-display="push"</code> animates both the panel and page at the same time.</p>

		<p>Here is an example of a panel with a custom position and display option set:</p>

<pre><code><![CDATA[
<div data-role="panel" id="mypanel" data-position="right" data-display="push">
	<!-- panel content goes here -->
</div>
]]></code></pre>

		<h4>Dynamic content</h4>
		<p>When you dynamically add content to a panel or make hidden content visible while the panel is open, you have to trigger the <code>updatelayout</code> event on the panel.</p>

<pre><code><![CDATA[
$( "#mypanel" ).trigger( "updatelayout" );
]]></code></pre>

		<p>The framework will check the new height of the panel contents and, in case this exceeds the screen height, set the page <code>min-height</code> to this height and unfix panels with <code>data-position-fixed="true"</code>. See also <strong>Panel positioning</strong>.</p>

		<h3>Opening a panel</h3>
		<p>A panel's visibility is toggled by a link somewhere on the page or by calling the panel's <code>open</code> method directly. The defaults place the panel on the left in "reveal" mode. Open a panel programmatically like this:</p>

<pre><code><![CDATA[
$( "#idofpanel" ).panel( "open" , optionsHash );
]]></code></pre>

		<p>To control a panel from a link, point the <code>href</code> to the <code>ID</code> of the panel you want to toggle (<code>mypanel</code> in the example below). This instructs the framework to bind the link to the panel. This link will toggle the visibility of the panel so tapping it will open the panel, and tapping it again will close it.</p>

<pre><code><![CDATA[
<a href="#mypanel">Open panel</a>
]]></code></pre>

		<iframe src="/resources/panel/example2.html" style="width:100%;height:440px;border:0px"></iframe>

		<p>When using markup to control panels, you can only have a single panel open at once. Clicking a link to open a panel while one is already open will auto-close the first. This is done to keep the markup-only configuration simple.</p>

		<h3>Closing a panel</h3>
		<p>Clicking the link that opened the panel, swiping left or right, or tapping the Esc key will close the panel. To turn off the swipe-to-close behavior, add the <code>data-swipe-close="false"</code> attribute to the panel.</p>

		<p>By default, panels can also be closed by clicking outside the panel onto the page contents. To prevent this behavior, add the <code>data-dismissible="false"</code> attribute to the panel. It's possible to have the panel and page sit side-by-side at wider screen widths and prevent the click-out-to-close behavior only above a certain screen width by applying a media query. See the responsive section below for details.</p>

		<p>A panel can also be closed by calling the panel's <code>close</code> method directly.</p>

<pre><code><![CDATA[
$( "#idofpanel" ).panel( "close" );
]]></code></pre>

		<p>It's common to also add a close button inside the panel. To add the link that will close the panel, add the <code>data-rel="close"</code> attribute to tell the framework to close that panel when clicked. It's important to ensure that this link also makes sense if JavaScript isn't available, so we recommend that the <code>href</code> points to the ID of the page to which the user should jump when closing. For example, if the button to open the panel is in the header bar that has and ID of <code>my-header</code>, the close link in the panel should be:</p>

<pre><code><![CDATA[
<a href="#my-header" data-rel="close">Close panel</a>
]]></code></pre>

		<h3>Panel animations</h3>
		<p>Panels will animate if the browser supports 3D transforms. The presence of such support is established by the same criteria for CSS animation support we use for page transitions. Panel animations use <code>translateX</code> CSS transforms to ensure they are hardware accelerated and smooth.</p>

		<p>The framework has a feature test to detect if the required CSS properties are supported and will fall back to a simple hide/show if not available. After thorough testing, we decided to not animate panels on less capable platforms because the choppier animations weren't a better experience than a simple hide/show.</p>

		<p>The <code>animate</code> option allows you to turn off panel animations for all devices. To turn off animations via markup, add the <code>data-animate="false"</code> attribute to the panel container.</p>

		<p>The use of hardware acceleration is triggered during initialization of the page to prevent blinks when opening a panel. Because this increases memory use you have to be aware of performance issues if you use long lists or scripts to dynamically inject content on a page with an animated panel.</p>

		<h3>Panel positioning</h3>
		<p>The panel will be displayed with the <code>position:absolute</code> CSS property, meaning it will scroll with the page. When a panel is opened the framework checks to see if the bottom of the panel contents is in view and, if not, scrolls to the top of the page.</p>

		<p>You can set a panel to <code>position:fixed</code>, so its contents will appear no matter how far down the page you're scrolled, by adding the <code>data-position-fixed="true"</code> attribute to the panel. The framework also checks to see if the panel contents will fit within the viewport before applying the fixed positioning because this property would prevent the panel contents from scrolling and using <code>overflow</code> is not well supported enough to use at this time. If the panel contents are too long to fit within the viewport, the framework will simply display the panel without fixed positioning.</p>

		<p>In general, we recommend that you place the buttons that open the panel at the very top of the screen which is the most common UI pattern for panels.  This will avoid the need to scroll and also makes the transitions a bit smoother.</p>

		<p>Note that there are issues with fixed positioning within Android WebView applications (not the browser) that can cause layout issues, especially when hardware acceleration isn't enabled. We recommend not to use the fixed position panel option if deploying to an Android app. Also, if you have a fixed panel on a page with fixed toolbars, the toolbars might not transition together with the page content.</p>

		<h3>Styling panels</h3>

		<p>By default, panels have very simple styles to let you customize them as needed. Panels are essentially just simple blocks with no margins that sit on either side of the page content. The framework wraps the panel content in a <code>div</code> with class <code>ui-panel-inner</code> which has a padding of 15 pixels. If needed you can override this with custom CSS or use option <code>classes.panelInner</code> to set a different class name for the <code>div</code>.</p>

		<p>Panels have a fixed width of 17em (272 pixels) which is narrow enough to still show some of the page contents when open to make clicking out to close easy, and still looks good on wider tablet or desktop screens. The styles to set widths on panels are fairly complex but these can be overridden with CSS as needed.</p>

		<p>Note that adding padding, borders, or margins directly to the panel container will alter the overall dimensions and could cause the positioning and animation to be affected. To avoid this, apply styles to the panel content wrapper (<code>.ui-panel-inner</code>).</p>

		<p>Other than the theme background, width and 100% height styles, panels have very little styling on their own. The default theme for panels is "a". You can set a different theme for the panel by adding a <code>data-theme</code> to the panel container, or set <code>data-theme="none"</code> and add your own classes to style it as needed.</p>

		<p>The framework applies the theme that is used for the page to the content wrapper. Before opening a panel that has display mode reveal or push, the page theme will be set to the same theme that is used for the panel. This is done to mask that most mobile browsers haven't finished painting the panel background when the animation to open it has already started. If you use a background image for a page, you have to set it for the <code>ui-body-*</code> class of the theme that you use for the page so it will be used as background of the content wrapper.</p>

		<h3>Making the panel responsive</h3>

		<p>When the push or reveal display is used, a panel pushes the page aside when it opens. Since some of the page is pushed offscreen, the panel is modal and must be closed to interact with the page content again. On larger screens, you may want to have the panel work more like a collapsible column that can be opened and used alongside the page to take better use of the screen real estate. </p>

		<p>To make the page work alongside the open panel, it needs to re-flow to a narrower width so it will fit next to the panel. This can be done purely with CSS by adding a left or right margin equal to the panel width (17em) to the page contents to force a re-flow. Second, the invisible layer placed over the page for the click out to dismiss behavior is hidden with CSS so you can click on the page and not close the menu. </p>

		<p>Here is an example of these rules wrapped in a media query to only apply this behavior above 35em (560px):</p>

<pre><code><![CDATA[
@media (min-width:35em) {

	/* wrap on wide viewports once open */

	.ui-panel-page-content-open.ui-panel-page-content-position-left {
		margin-right: 17em;
	}
	.ui-panel-page-content-open.ui-panel-page-content-position-right {
		margin-left: 17em;
	}
	.ui-panel-page-content-open {
		width: auto;
	}

	/* disable "dismiss" on wide viewports */
	.ui-panel-dismiss {
		display: none;
	}

	/* same as the above but for panels with display mode "push" only */

	.ui-panel-page-content-open.ui-panel-page-content-position-left.ui-panel-page-content-display-push {
		margin-right: 17em;
	}
	.ui-panel-page-content-open.ui-panel-page-content-position-right.ui-panel-page-content-display-push {
		margin-left: 17em;
	}
	.ui-panel-page-content-open.ui-panel-page-content-display-push {
		width: auto;
	}

	.ui-panel-dismiss-display-push {
		display: none;
	}
}
]]></code></pre>

		<h4>Applying a preset breakpoint</h4>
		<p>Included in the widget styles is a breakpoint preset for this behavior that kicks in at 55em (880px). This breakpoint is not applied by default to make it easier for you to write custom breakpoints that work best for your content and design. To apply the breakpoint preset, add the <code>ui-responsive-panel</code> class to the <em>page</em> (not the panel).</p>

  </longdesc>
	<added>1.3</added>
	<options>
		<option name="animate" default="true" example-value="false">
			<desc>Sets whether the panel will animate when opening and closing. If set to false, the panel will just appear and disappear without animation. This is recommended for fastest performance.
				<p>This option is also exposed as a data attribute:<code>data-animate="false"</code> on the panel container.</p>
			</desc>
			<type name="Boolean" />
		</option>
		<option name="classes.animate" default='"ui-panel-animate"'>
			<desc>Class added to the panel, page contents wrapper and fixed toolbars when option animate is true and the 3D transform feature test returns <code>true</code>.</desc>
			<type name="String" />
		</option>
		<option name="classes.contentFixedToolbar" default='"ui-panel-fixed-toolbar-wrap"' removed="1.4">
			<desc>
				<div class="warning"><strong>Note:</strong> This class is no longer used as of 1.4.0, so setting this option will have no effect on the panel.</div>
				<p>Class added to the page container to suppress scrolling horizontally</p>
			</desc>
			<type name="String" />
		</option>
		<option name="classes.contentFixedToolbarClosed" default='"ui-panel-content-fixed-toolbar-closed"' removed="1.4">
			<desc>
				<div class="warning"><strong>Note:</strong> This class is no longer used as of 1.4.0, so setting this option will have no effect on the panel.</div>
				<p>Class added to fixed toolbars after the close animation is complete.</p>
			</desc>
			<type name="String" />
		</option>
		<option name="classes.contentFixedToolbarOpen" default='"ui-panel-content-fixed-toolbar-open"' removed="1.4">
			<desc>
				<div class="warning"><strong>Note:</strong> This class is no longer used as of 1.4.0, so setting this option will have no effect on the panel.</div>
				<p>Class added to fixed toolbars when the panel is opening.</p>
			</desc>
			<type name="String" />
		</option>
		<option name="classes.contentWrap" default='"ui-panel-content-wrap"' removed="1.4">
			<desc>
				<div class="warning"><strong>Note:</strong> This class is no longer used as of 1.4.0, so setting this option will have no effect on the panel.</div>
				<p>Class added to the wrapper injected around the page contents (header, content, footer), needed for positioning of the panel.</p>
			</desc>
			<type name="String" />
		</option>
		<option name="classes.contentWrapClosed" default='"ui-panel-content-wrap-closed"' removed="1.4">
			<desc>
				<div class="warning"><strong>Note:</strong> This class is no longer used as of 1.4.0, so setting this option will have no effect on the panel.</div>
				<p>Class added to the page contents wrapper after the close animation is complete.</p>
			</desc>
			<type name="String" />
		</option>
		<option name="classes.contentWrapOpen" default='"ui-panel-content-wrap-open"' removed="1.4">
			<desc>
				<div class="warning"><strong>Note:</strong> This class is no longer used as of 1.4.0, so setting this option will have no effect on the panel.</div>
				<p>Class added to the wrapper injected around the page contents (header, content, footer) when the panel is opening. Used for targeting hardware acceleration only during transitions.</p>
			</desc>
			<type name="String" />
		</option>
		<option name="classes.modal" default='"ui-panel-dismiss"'>
			<desc>Class added to the overlay on the page to dismiss the panel when hidden.</desc>
			<type name="String" />
		</option>
		<option name="classes.modalOpen" default='"ui-panel-dismiss-open"'>
			<desc>Class added to the invisible overlay over the page when the panel is open. Used to dismiss the panel.</desc>
			<type name="String" />
		</option>
		<option name="classes.pageContainer" default='"ui-panel-page-container"'>
			<desc>Class applied to the page container.</desc>
			<type name="String" />
		</option>
		<option name="classes.pageContentPrefix" default='"ui-panel-page-content"'>
			<desc>Used for wrapper and fixed toolbars position, display and open classes.</desc>
			<type name="String" />
		</option>
		<option name="classes.pageFixedToolbar" default='"ui-panel-fixed-toolbar"'>
			<desc>Class applied to any fixed toolbars.</desc>
			<type name="String" />
		</option>
		<option name="classes.pagePanel" default='"ui-page-panel"' removed="1.4">
			<desc>
				<div class="warning"><strong>Note:</strong> This class is no longer used as of 1.4.0, so setting this option will have no effect on the panel.</div>
				<p>Class added to the page container when a panel widget is present.</p>
			</desc>
			<type name="String" />
		</option>
		<option name="classes.pagePanelOpen" default='"ui-page-panel-open"' removed="1.4">
			<desc>
				<div class="warning"><strong>Note:</strong> This class is no longer used as of 1.4.0, so setting this option will have no effect on the panel.</div>
				<p>Class added to the page when a panel is open.</p>
			</desc>
			<type name="String" />
		</option>
		<option name="classes.panel" default='"ui-panel"'>
			<desc>Class added to the panel.</desc>
			<type name="String" />
		</option>
		<option name="classes.panelClosed" default='"ui-panel-closed"'>
			<desc>Class added to the panel when closed.</desc>
			<type name="String" />
		</option>
		<option name="classes.panelFixed" default='"ui-panel-fixed"'>
			<desc>Class added to the panel when fixed positioning is applied.</desc>
			<type name="String" />
		</option>
		<option name="classes.panelInner" default='"ui-panel-inner"'>
			<desc>Class added to the panel contents wrapper div.</desc>
			<type name="String" />
		</option>
		<option name="classes.panelOpen" default='"ui-panel-open"'>
			<desc>Class added to the panel when opening. Used for targeting hardware acceleration only during transitions.</desc>
			<type name="String" />
		</option>
		<xi:include href="../includes/widget-option-defaults.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
		<xi:include href="../includes/widget-option-disabled.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
		<option name="dismissible" default="true" example-value="false">
			<desc>Sets whether the panel can be closed by clicking outside onto the page.
				<p>This option is also exposed as a data attribute:<code>data-dismissible="false"</code> on the link that opens the panel.</p>
			</desc>
			<type name="Boolean" />
		</option>
		<option name="display" default='"reveal"'  example-value='"overlay"'>
			<desc>The relationship of the panel to the page contents. This option accepts one of three values:
				<table>
					<tr><td class="enum-value">"reveal"</td><td>Push the page over</td></tr>
					<tr><td class="enum-value">"push"</td><td>Re-flow the content to fit the panel content as a column</td></tr>
					<tr><td class="enum-value">"overlay"</td><td>Sit over the content</td></tr>
				</table>
				<p>This option is also exposed as a data attribute:<code>data-display="push"</code> on the link that opens the panel.</p>
			</desc>
			<type name="String" />
		</option>
		<xi:include href="../includes/widget-option-initSelector.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
		<option name="position" default='"left"'  example-value='"right"'>
			<desc>The side of the screen the panel appears on. Values can be "left" or "right".
				<p>This option is also exposed as a data attribute:<code>data-position="right"</code> on the link that opens the panel.</p>
			</desc>
			<type name="String" />
		</option>
		<option name="positionFixed" default="false" example-value="true">
			<desc>Sets whether the panel has fixed positioning so the contents are in view even if the page is scrolled down. This also allows the page to scroll while the panel stays fixed. We recommend not to enable this feature when panels are used withing Android apps because of poor performance and display issues.
				<p>This option is also exposed as a data attribute:<code>data-position-fixed=true</code> on the panel.</p>
			</desc>
			<type name="Boolean" />
		</option>
		<option name="swipeClose" default="true" example-value="false">
			<desc>Sets whether the panel can be closed by swiping left or right over the panel.
				<p>This option is also exposed as a data attribute:<code>data-swipe-close=false</code> on the panel.</p>
			</desc>
			<type name="Boolean" />
		</option>
		<option name="theme" default='null, inherited from parent' example-value='"b"'>
			<desc>
				Sets the color scheme (swatch) for the <placeholder name="name" /> widget. It accepts a single letter from a-z that maps to the swatches included in your theme.
				<p>Possible values: swatch letter (a-z).</p>
				<p>This option is also exposed as a data attribute: <code>data-theme="b"</code>.</p>
			</desc>
			<type name="String" />
		</option>
	</options>
	<events>
		<event name="beforeclose">
			<desc>Triggered at the start of the process of closing a panel
			</desc>
			<argument name="event" type="Event">
				<desc></desc>
			</argument>
			<argument name="ui" type="Object">
				<desc></desc>
			</argument>
		</event>
		<event name="beforeopen">
			<desc>Triggered at the start of the process of opening a panel
			</desc>
			<argument name="event" type="Event">
				<desc></desc>
			</argument>
			<argument name="ui" type="Object">
				<desc></desc>
			</argument>
		</event>
		<event name="create">
			<desc>Triggered when a panel is created
			</desc>
			<argument name="event" type="Event">
				<desc></desc>
			</argument>
			<argument name="ui" type="Object">
				<desc></desc>
			</argument>
		</event>
		<event name="close">
			<desc>Triggered when the process (and animation) of closing a panel is finished
			</desc>
			<argument name="event" type="Event">
				<desc></desc>
			</argument>
			<argument name="ui" type="Object">
				<desc></desc>
			</argument>
		</event>
		<event name="open">
			<desc>Triggered when the process (and animation) of opening a panel is finished
			</desc>
			<argument name="event" type="Event">
				<desc></desc>
			</argument>
			<argument name="ui" type="Object">
				<desc></desc>
			</argument>
		</event>
	</events>
	<methods>
		<method name="close">
			<desc>closes a panel.
			</desc>
		</method>
		<method name="open">
			<desc>opens a panel.
			</desc>
		</method>
		<method name="toggle">
			<desc>toggles the visibility the panel so it will open a closed panel or close and open panel.
			</desc>
		</method>
	</methods>
	<example>
		<height>450px</height>
		<desc>A basic example of a panel.</desc>
		<css><![CDATA[
	.panel-content {
		padding: 1em;
	}
]]></css>
		<html><![CDATA[
<div data-role="page" id="page1">
	<div data-role="header">
		<h1>jQuery Mobile Example</h1>
	</div>
	<div role="main" class="ui-content">
		<a href="#defaultpanel" data-role="button" data-inline="true" data-icon="bars">Default panel</a>
	</div>

	<!-- defaultpanel  -->
	<div data-role="panel" id="defaultpanel" data-theme="b">

		<div class="panel-content">
			<h3>Default panel options</h3>
			<p>This panel has all the default options: positioned on the left with the reveal display mode. The panel markup is <em>before</em> the header, content and footer in the source order.</p>
			<p>To close, click off the panel, swipe left or right, hit the Esc key, or use the button below:</p>
			<a href="#demo-links" data-rel="close" data-role="button" data-theme="a" data-icon="delete" data-inline="true">Close panel</a>
		</div><!-- /content wrapper for padding -->
	</div><!-- /defaultpanel -->
</div>
]]></html>
	</example>
	<category slug="widgets"/>
</entry>