Skip to content

Commit 5e5a43e

Browse files
toddparkertoddparker
committed
Panel: Docs cleanup
1 parent 0aa3617 commit 5e5a43e

File tree

5 files changed

+393
-413
lines changed

5 files changed

+393
-413
lines changed

‎docs/panels/events.html

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
<!DOCTYPE html>
2+
<html>
3+
<head>
4+
<meta charset="utf-8">
5+
<meta name="viewport" content="width=device-width, initial-scale=1">
6+
<title>jQuery Mobile Docs - Slide Panel</title>
7+
<link rel="stylesheet" href="../../css/themes/default/jquery.mobile.css" />
8+
<link rel="stylesheet" href="../_assets/css/jqm-docs.css"/>
9+
10+
<script src="../../js/jquery.js"></script>
11+
<script src="../../docs/_assets/js/jqm-docs.js"></script>
12+
<script src="../../js/"></script>
13+
</head>
14+
<body>
15+
<div data-role="page" class="ui-responsive-panel">
16+
17+
<div data-role="header" data-theme="f">
18+
<h2>Panels</h2>
19+
<a href="../../" data-icon="home" data-iconpos="notext" data-direction="reverse">Home</a>
20+
<a href="../nav.html" data-icon="search" data-iconpos="notext" data-rel="dialog" data-transition="fade">Search</a>
21+
</div><!-- /header -->
22+
23+
24+
<div data-role="content">
25+
<h1 id="demo-links">Panels</h1>
26+
27+
<ul data-role="controlgroup" data-type="horizontal" class="localnav">
28+
<li><a href="index.html" data-role="button" data-transition="fade">Basics</a></li>
29+
<li><a href="options.html" data-role="button" data-transition="fade">Options</a></li>
30+
<li><a href="methods.html" data-role="button" data-transition="fade">Methods</a></li>
31+
<li><a href="events.html" data-role="button" data-transition="fade" class="ui-btn-active">Events</a></li>
32+
</ul>
33+
34+
35+
<dl>
36+
<dt><code>create</code> Type: panelcreate</dt>
37+
<dd>Triggered when the panel is created.</dd>
38+
</dl>
39+
</div><!-- /content -->
40+
41+
<div data-role="footer" class="footer-docs" data-theme="c">
42+
<p class="jqm-version"></p>
43+
<p>&copy; 2012 jQuery Foundation and other contributors</p>
44+
</div>
45+
46+
47+
48+
</div><!-- /page -->
49+
</body>
50+
</html>

‎docs/panels/index.html

Lines changed: 31 additions & 108 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@
1616

1717
<style>
1818
.panel-content { padding:15px; }
19-
</style>
19+
</style>
2020

2121
<!-- defaultpanel -->
2222
<div data-role="panel" id="defaultpanel" data-theme="b">
@@ -35,13 +35,21 @@ <h3>Default panel options</h3>
3535

3636

3737
<div data-role="header" data-theme="f" data-position="fixed">
38-
<h1>Panels</h1>
38+
<h2>Panels</h2>
3939
<a href="../../" data-icon="home" data-iconpos="notext" data-direction="reverse">Home</a>
4040
<a href="../nav.html" data-icon="search" data-iconpos="notext" data-rel="dialog" data-transition="fade">Search</a>
4141
</div><!-- /header -->
42+
4243
<div data-role="content">
43-
<h1 id="demo-links">Panels</h1>
44-
44+
<h2 id="demo-links">Panels</h2>
45+
46+
<ul data-role="controlgroup" data-type="horizontal" class="localnav">
47+
<li><a href="index.html" data-role="button" data-transition="fade" class="ui-btn-active">Basics</a></li>
48+
<li><a href="options.html" data-role="button" data-transition="fade">Options</a></li>
49+
<li><a href="methods.html" data-role="button" data-transition="fade">Methods</a></li>
50+
<li><a href="events.html" data-role="button" data-transition="fade">Events</a></li>
51+
</ul>
52+
4553
<p>Panels are designed to be as flexible as possible to make it easy to create menus, collapsible columns, drawers, inspectors panes and more. </p>
4654

4755

@@ -88,19 +96,21 @@ <h2>Panel markup conventions</h2>
8896
<p>A panel consists of a container with a <code>data-role=&quot;panel&quot;</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>
8997

9098
<pre><code>
91-
&lt;div <strong>data-role=&quot;panel&quot; id=&quot;leftpanel1&quot;</strong>&gt;
99+
&lt;div <strong>data-role=&quot;panel&quot; id=&quot;mypanel&quot;</strong>&gt;
92100
&lt;!-- panel content goes here --&gt;
93101
&lt;/div&gt;
94102
</code></pre>
95103

96104
<p>The <strong>position</strong> of the panel on the screen is set by the <code>data-position</code> attribute. The 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>
97105

98-
<p>The <strong>display mode</strong> of the panel is set by the <code>data-display</code> attribute. The defaults to <code>overlay</code>, meaning the panel will appear to sit under the page and is revealed as the page slides away. Specify <code>data-display="overlay"</code> for it to appear on top of the page contents. A third mode, <code>data-display="push"</code> looks similar to reveal on smaller screens, but at wider widths, the panel slides in and causes the page contents to re-flow to make room so the panel can stay open, so it works like a dismissable column.</p>
106+
<p>The <strong>display mode</strong> of the panel is set by the <code>data-display</code> attribute. The defaults to <code>overlay</code>, meaning the panel will appear on top of the page contents. Specify <code>data-display="reveal"</code> for the panel to sit under the page and reveal as the page slides away. A third mode, <code>data-display="push"</code> animates both the panel and page at the same time.</p>
99107

100108
<p>The overlay style panel will always be the smoothest and most reliable display mode, especially if combined with fixed toolbars so we recommend you use that mode if possible.</p>
109+
110+
<p>Here is an example of a panel with a custom position and display option set:</p>
101111

102112
<pre><code>
103-
&lt;div data-role=&quot;panel&quot; id=&quot;leftpanel1&quot; data-position=&quot;left&quot; data-display=&quot;reveal&quot;&gt;
113+
&lt;div data-role=&quot;panel&quot; id=&quot;mypanel&quot; <strong>data-position=&quot;right&quot; data-display=&quot;reveal&quot;</strong>&gt;
104114
&lt;!-- panel content goes here --&gt;
105115
&lt;/div&gt;
106116
</code></pre>
@@ -109,17 +119,17 @@ <h2>Panel markup conventions</h2>
109119

110120
<h2>Opening a panel</h2>
111121

112-
<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.</p>
122+
<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 and will open over the page (overlay display mode). Open a panel programmatically like this:</p>
113123

114124
<pre><code>$( "#idofpanel" ).panel( "open" , optionsHash );</code></pre>
115125

116-
<pre><code>
117-
&lt;a href=&quot;#mypanel&quot; <strong>data-rel=&quot;panel&quot;</strong>&gt;Open panel&lt;/a&gt;
118-
</code></pre>
119-
<p>This will create a link that opens our panel with the default options. The defaults place the panel on the left and will push the page over when it opens (reveal mode). </p>
126+
120127

121-
<p>To control a panel from a link, point the <code>href</code> to references the <code>ID</code> of the panel you want to toggle (<code>mypanel</code> in the example above). This instructs the framework to bind the link to the popup. This link will toggle the visibility of the popup so tapping it will open the panel, and tapping it again will close it.</p>
128+
<p>To control a panel from a link, point the <code>href</code> to references the <code>ID</code> of the panel you want to toggle (<code>mypanel</code> in the example above). 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>
122129

130+
<pre><code>
131+
&lt;a href=&quot;#mypanel&quot;&gt;Open panel&lt;/a&gt;
132+
</code></pre>
123133

124134
<a href="#defaultpanel" data-role="button" data-inline="true" data-icon="bars">Default panel</a>
125135

@@ -136,15 +146,15 @@ <h2>Opening a panel</h2>
136146

137147
<h2>Closing a panel</h2>
138148

139-
<p>Clicking the link that opened the panel, swiping left or right, or tapping the Esc key will close the panel. </p>
149+
<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 swipt o close behavior, add the <code>data-swipe-close="false"</code> attribute to the panel.</p>
140150

141-
<p>By default, panels can also be closed clicking outside the panel onto the page contents. To prevent this behavior, add the <code>data-dismissible="false"</code> attribute to the panel. Note the since the <code>push</code> mode is designed to have the panel and page to sit side-by-side at wider screen widths, the panel won't be dismissed by clicking on the page on larger screens, regardless of the dismissible settings.</p>
151+
<p>By default, panels can also be closed 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>
142152

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

145155
<pre><code>$( "#idofpanel" ).panel( "close" );</code></pre>
146156

147-
<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 where the user should jump to when closing. For example, if the button to open the panel is in the heder bar that has and ID of <code>my-header</code>, the close link in the panel should be:</p>
157+
<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 where the user should jump to 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>
148158

149159
<pre><code>
150160
&lt;a href=&quot;#my-header&quot; <strong>data-rel=&quot;close&quot;</strong>&gt;Close panel&lt;/a&gt;
@@ -157,14 +167,14 @@ <h2>Panel animations</h2>
157167

158168
<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>
159169

160-
<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 popup container.</p>
170+
<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>
161171

162172

163173
<h2>Panel + fixed positioning</h2>
164174

165175
<p>The panel will be displayed with the <code>position:fixed</code> CSS property so their contents will appear no matter how far down the page you're scrolled. 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.</p>
166176

167-
<p>If a browser doesn't support fixed positioning or if the panel contents are too long to fit within the viewport, the framework will simply display the panel without fixed positioning. If the user has scrolled down and opens a panel, they may need to scroll up to view the contents. </p>
177+
<p>If a browser doesn't support fixed positioning or if the panel contents are too long to fit within the viewport, the framework will simply display the panel without fixed positioning. If the user has scrolled down and opens a panel, they may need to scroll up to view the contents. Fixed positioning can be disabled by adding the <code>data-position-fixed="false"</code> attribute to the panel.</p>
168178

169179
<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>
170180

@@ -176,9 +186,10 @@ <h2>Styling panels</h2>
176186

177187
<p>By default, panels have very simple styles to let you customize them as needed. Panels are essentially just simple blocks with no padding or margins that sit on either side of the page content. </p>
178188

179-
<p>The framework does need to set a width in order for the CSS animations to work correctly so below 25ems (400px), the panel is set to 80% of the screen width. Above 400px, the panel has a max width of 20ems (320px) since that is a typical panel size. Unfortunately, the styles to set widths on panels are fairly complex but these can be overridden with CSS as needed.</p>
189+
<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>
180190

181191
<p>Other than the width and 100% height styles, panels have very little styling on their own. You can set a theme on the panel by add a <code>data-theme</code> to the panel container or add your own classes to style it as needed.</p>
192+
182193
<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.</p>
183194

184195
<p>To add padding to a panel, we recommend adding a container inside the panel and applying styles to that to avoid any issues. All the examples on this page follow this pattern.</p>
@@ -210,95 +221,7 @@ <h4>Applying a preset breakpoint</h4>
210221
<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 wrapper</em> (not the panel).</p>
211222

212223

213-
<h2>Options</h2>
214-
215-
216-
<dl>
217-
218-
<dt><code>animate</code> default: true</dt>
219-
<dd>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. Also available via the <code>data-animate</code> attribute on the popup container.</dd>
220-
221-
<dt><code>dismissible</code> default: true</dt>
222-
<dd>Sets whether the panel can be closed by clicking outside onto the page. Also available via the <code>data-dismissible</code> attribute on the link that opens the popup.</dd>
223-
224-
<dt><code>display</code> default: "overlay"</dt>
225-
<dd>The relationship of the panel to the page contents. Can either push the page over ("reveal"), re-flow the content to fit the panel content as a column ("push"), or sit over the content ("overlay"). Also available via the <code>data-display</code> attribute on the link that opens the popup.</dd>
226-
227-
<dt><code>initSelector</code> default: ":jqmData(role='panel')"</dt>
228-
<dd>The role (or and valid jQuery selector) used to trigger auto-initialization of the panel widget.</dd>
229-
230-
<dt><code>position</code> default: "left"</dt>
231-
<dd>The side of the screen the panel appears on. Values can be "left" or "right. Also available via the <code>data-position</code> attribute on the link that opens the popup.</dd>
232-
233-
<dt><code>theme</code> default: null</dt>
234-
<dd>Theme swatch for the panel. Can be any valid swatch letter in your theme (a-z). Also available via the <code>data-theme</code> attribute on the popup container.</dd>
235-
236-
</dl>
237-
238-
<h3>Classes Option</h3>
239-
<p>The <code>classes</code> option define the structural classnames that the plugin uses. This is only configurable via JavaScript because it expects an object literal value.</p>
240-
241-
<dl>
242-
<dt><code>classes.panel</code> default: "ui-panel"</dt>
243-
<dd>Class added to the panel.</dd>
244-
245-
<dt><code>classes.panelOpen</code> default: "ui-panel-open"</dt>
246-
<dd>Class added to the panel when opening. Used for targeting hardware acceleration only during transitions.</dd>
247-
248-
<dt><code>classes.modal</code> default: "ui-panel-dismiss"</dt>
249-
<dd>Class added to the overlay on the page to dismiss the panel when hidden.</dd>
250-
251-
<dt><code>classes.modalOpen</code> default: "ui-panel-dismiss-open"</dt>
252-
<dd>Class added to the invisible overlay over the page when the popup is open. Used to dismiss the panel.</dd>
253-
254-
<dt><code>classes.openComplete</code> default: "ui-panel-open-complete"</dt>
255-
<dd>Class added to the page when the panel animation is complete.</dd>
256-
257-
<dt><code>classes.contentWrap</code> default: "ui-panel-content-wrap"</dt>
258-
<dd>Class added to the wrapper injected around the page contents (header, content, footer), needed for positioning of the panel.</dd>
259-
260-
<dt><code>classes.contentWrapOpen</code> default: "ui-panel-content-wrap-open"</dt>
261-
<dd>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.</dd>
262-
263-
<dt><code>classes.wrapOpenComplete</code> default: "ui-panel-content-wrap-open-complete"</dt>
264-
<dd>Class added to the page contents wrapper after the open animaation is complete.</dd>
265-
266-
<dt><code>classes.pageBlock</code> default: "ui-panel-page-block"</dt>
267-
<dd>Class added to the page container to suppress scrolling horizontally</dd>
268-
</dl>
269-
270-
271-
<h2>Methods</h2>
272-
273-
<dl>
274-
<dt><code>close</code></dt>
275-
<dd>Closes the panel.
276-
.<pre><code>$( myPanel ).panel( "close" );</code></pre>
277-
</dd>
278-
279-
<dt><code>open</code></dt>
280-
<dd>Opens the panel.
281-
<pre><code>$( myPanel ).panel( "open" );</code></pre>
282-
</dd>
283-
284-
<dt><code>refresh</code></dt>
285-
<dd>Re-enhances any new markup in the panel.
286-
<pre><code>$( myPanel ).panel( "refresh" );</code></pre>
287-
</dd>
288-
289-
<dt><code>toggle</code></dt>
290-
<dd>Toggles the visibility the panel so it will open a closed panel or close and open panel.
291-
<pre><code>$( myPanel ).panel( "toggle" );</code></pre>
292-
</dd>
293-
</dl>
294-
295-
296-
<h2>Events</h2>
297-
298-
<dl>
299-
<dt><code>create</code> Type: panelcreate</dt>
300-
<dd>Triggered when the panel is created.</dd>
301-
</dl>
224+
302225
</div><!-- /content -->
303226

304227
<div data-role="footer" class="footer-docs" data-theme="c">

0 commit comments

Comments
 (0)