libs/js/jquery-mobile-1.1.0/docs/toolbars/bars-fixed.html

   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 Framework - Fixed Toolbars</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
  14 </head>
  15 <body>
  16
  17 <div data-role="page" class="type-interior">
  18
  19         <div data-role="header" data-position="fixed" data-theme="f">
  20                 <h1>Fixed toolbars</h1>
  21                 <a href="../../" data-icon="home" data-iconpos="notext" data-direction="reverse">Home</a>
  22                 <a href="../nav.html" data-icon="search" data-iconpos="notext" data-rel="dialog" data-transition="fade">Search</a>
  23         </div>
  24
  25         <div data-role="content">
  26                 <div class="content-primary">
  27                                 <h2>Fixed toolbars</h2>
  28
  29                             <ul data-role="controlgroup" data-type="horizontal" class="localnav">
  30                               <li><a href="bars-fixed.html" data-role="button" data-transition="fade" class="ui-btn-active">Basics</a></li>
  31                               <li><a href="bars-fixed-options.html" data-role="button" data-transition="fade">Options</a></li>
  32                               <li><a href="bars-fixed-methods.html" data-role="button" data-transition="fade">Methods</a></li>
  33                               <li><a href="bars-fixed-events.html" data-role="button" data-transition="fade">Events</a></li>
  34                             </ul>
  35
  36
  37                 <p>In browsers that support CSS <code>position: fixed</code> (most desktop browsers, iOS5+, Android 2.2+, BlackBerry 6, and others), toolbars that use the "fixedtoolbar" plugin will be fixed to the top or bottom of the viewport, while the page content scrolls freely in between. In browsers that don't support fixed positioning, the toolbars will remain positioned in flow, at the top or bottom of the page. </p>
  38
  39                 <p>To enable this behavior on a header or footer, add the <code>data-position="fixed"</code> attribute to a jQuery Mobile header or footer element.</p>
  40
  41                 <p>Fixed header markup example:</p>
  42                 <pre><code>
  43 &lt;div data-role=&quot;header&quot; <strong>data-position=&quot;fixed&quot;</strong>&gt;
  44         &lt;h1&gt;Fixed Header!&lt;/h1&gt;
  45 &lt;/div&gt;
  46                 </code></pre>
  47
  48                 <p>Fixed footer markup example:</p>
  49                 <pre><code>
  50 &lt;div data-role=&quot;footer&quot; <strong>data-position=&quot;fixed&quot;</strong>&gt;
  51         &lt;h1&gt;Fixed Footer!&lt;/h1&gt;
  52 &lt;/div&gt;
  53                 </code></pre>
  54
  55                 <h2>Fullscreen Toolbars</h2>
  56                 <p><a href="bars-fullscreen.html">Fullscreen</a> fixed toolbars sit on top of the content at all times when they are visible, and unlike regular fixed toolbars, fullscreen toolbars do not fall back to static positioning when toggled. Instead they disappear from the screen entirely. Fullscreen toolbars are ideal for more immersive interfaces, like a photo viewer that is meant to fill the entire screen with the photo itself and no distractions.</p>
  57
  58                                 <p>To enable this option on a fixed header or footer, add the <code>data-fullscreen</code> attribute to the element.</p>
  59
  60                                 <pre><code>
  61 &lt;div data-role=&quot;header&quot; data-position=&quot;fixed&quot; data-fullscreen=&quot;true&quot;&gt;
  62         &lt;h1&gt;Fixed Header!&lt;/h1&gt;
  63 &lt;/div&gt;
  64                                 </code></pre>
  65
  66
  67                 <h2>Forms in toolbars</h2>
  68
  69                 <p>While all form elements are now tested to work correctly within <em>static</em> toolbars as of jQuery Mobile 1.1, we recommend extensive testing when using form elements within <em>fixed</em> toolbars or within any <code>position: fixed</code> elements. This can potentially trigger a number of unpredictable issues in various mobile browsers, Android 2.2/2.3 in particular (detailed in <b>Known issues in Android 2.2/2.3</b>, below).</p>
  70
  71                 <h2>Changes in jQuery Mobile 1.1</h2>
  72
  73                 <p>Prior to version 1.1, jQuery Mobile used dynamically re-positioned toolbars for the fixed header effect because very few mobile browsers supported the <code>position:fixed</code> CSS property, and simulating fixed support through the use of "fake" JavaScript overflow-scrolling behavior would have reduced our browser support reach, in addition to feeling unnatural on certain platforms. This behavior was not ideal, and jQuery Mobile 1.1 took a new approach to fixed toolbars that allows much broader support. The framework now offers true fixed toolbars on many popular platforms, while gracefully degrading non-supporting platforms to static positioning.</p>
  74
  75                 <h3>Polyfilling older platforms</h3>
  76                 <p>The fixed toolbar plugin degrades gracefully in platforms that do not support CSS <code>position:fixed</code> properly, such as iOS4.3. If you still need to support fixed toolbars on that platform (with the show/hide behavior) included in previous releases, Filament Group has developed a polyfill that you can use.</p>
  77
  78                 <ul>
  79                                 <li><a href="https://github.com/filamentgroup/jQuery-Mobile-FixedToolbar-Legacy-Polyfill">Github code repository with CSS, and JavaScript required for the fixed toolbars polyfill</a></li>
  80                                 <li><a href="http://filamentgroup.github.com/jQuery-Mobile-FixedToolbar-Legacy-Polyfill/">Preview URL using the code in the repo above</a></li>
  81                 </ul>
  82
  83                 <p>Just include the CSS and JS files after your references to jQuery Mobile and Fixed toolbars will work similar to jQuery Mobile 1.0 in iOS4.3, with the inclusion of the new API for the 1.1 fixedtoolbar plugin.</p>
  84
  85                 <p>If you have any improvements to suggest, fork the <a href="https://github.com/filamentgroup/jQuery-Mobile-FixedToolbar-Legacy-Polyfill">gist</a> on github and let us know!</p>
  86
  87                 <h2>Known issue with form controls inside fixed toolbars, and programatic scroll</h2>
  88                 <p>An obscure issue exists in iOS5 and some Android platforms where form controls placed inside fixed-positioned containers can lose their hit area when the window is programatically scrolled (using <code>window.scrollTo</code> for example). This is not an issue specific to jQuery Mobile, but because of it, we recommend not programatically scrolling a document when using form controls inside jQuery Mobile fixed toolbars. <a href="https://github.com/scottjehl/Device-Bugs/issues/1">This ticket</a> from the <a href="https://github.com/scottjehl/Device-Bugs/">Device Bugs project</a> tracker explains this problem in more detail.</p>
  89
  90
  91                 <h2>Known issues in Android 2.2/2.3</h2>
  92                 <p>Android 2.2/2.3’s implementation of <code>position: fixed;</code> can, in conjunction with seemingly unrelated styles and markup patterns, cause a number of strange issues, particularly in the case of <code>position: absolute</code> elements inside of <code>position: fixed</code> elements. While we’ve done our best to work around a number of these unique bugs within the scope of the library, custom styles may cause a number of issues.</p>
  93                 <ul>
  94                         <li>Form elements elsewhere on the page—select menus in particular—can fail to respond to user interaction when an <em>empty</em> absolute positioned element is placed within a fixed position element. In rare cases—and specific to Android 2.2—this can cause <em>entire pages</em> to fail to respond to user interaction. This can seemingly be solved by adding any character to the absolute positioned element, including a non-breaking space, and in some cases even whitespace.</li>
  95                         <li>The above-described issue can also be triggered by an absolute positioned image inside of a fixed position element, but <em>only</em> when that image is using something <em>other than its inherent dimensions</em>. If a height or width is specified on the image using CSS, or the image src is invalid (thus having no inherent height and width), this issue can occur. If an image that is inherently, say, 50x50 pixels is placed in a fixed element and left at its inherent dimensions, this issue does not seem to occur.</li>
  96                         <li>When a <code>position: fixed</code> element appears anywhere on a page, most 2D CSS transforms will fail. Oddly, only <code>translate</code> transforms seem unaffected by this. Even more oddly, this issue is solved by setting a CSS <code>opacity</code> of .9 or below on the parent of the fixed element.</li>
  97                         <li>Combinations of <code>position: fixed</code> and overflow properties are best avoided, as both have been known to cause unpredictable issues in older versions of Android OS.</li>
  98                         <li>Any element that triggers the on-screen keyboard, when placed inside a <code>position: fixed</code> element, will fail to respond to user input when using anything other than the default keyboard. This includes Swype, XT9 or, it seems, any input method apart from the standard non-predictive keyboard.</li>
  99                 </ul>
 100
 101                 <p>While we will continue to try to find ways to mitigate these bugs as best we can, we currently advise against implementing fixed toolbars containing complicated user styles and form elements without extensive testing in all versions of Android’s native browser.</p>
 102
 103                 <p>The following pages are designed to test fixed toolbars and form elements:
 104                                         <a href="bars-fixed-forms-a.html">demo app</a>,
 105                                         <a href="bars-fixed-forms-b.html">text inputs</a>,
 106                                         <a href="bars-fixed-forms-c.html">search inputs</a>,
 107                                         <a href="bars-fixed-forms-d.html">radio toggles</a>,
 108                                         <a href="bars-fixed-forms-e.html">checkbox toggles</a>,
 109                                         <a href="bars-fixed-forms-f.html">slider</a>,
 110                                         <a href="bars-fixed-forms-g.html">select</a>, and
 111                                         <a href="bars-fixed-forms-h.html">buttons</a>.</p>
 112
 113
 114 <div class="ui-body ui-body-e">
 115                 <h2>No longer supported: touchOverflowEnabled</h2>
 116
 117                 <p>Prior to jQuery Mobile 1.1, true fixed toolbar support was contingent on native browser support for the CSS property <code>overflow-scrolling: touch</code>, which is currently only supported in iOS5. As of version 1.1, jQuery Mobile no longer uses this CSS property at all. We've removed all internal usage of this property in the framework, but we've left it defined globally on the $.mobile object to reduce the risk that its removal will cause trouble with existing applications. This property is flagged for removal, so please update your code to no longer use it. The support test for this property, however, remains defined under <code>$.support</code> and we have no plans to remove that test at this time. </p>
 118 </div>
 119                 <hr>
 120
 121
 122                 <h2>The rest of the page is just sample content to make the page very long</h2>
 123
 124                         <p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. <em>Aenean ultricies mi vitae est.</em> Mauris placerat eleifend leo. Quisque sit amet est et sapien ullamcorper pharetra. Vestibulum erat wisi, condimentum sed, <code>commodo vitae</code>, ornare sit amet, wisi. Aenean fermentum, elit eget tincidunt condimentum, eros ipsum rutrum orci, sagittis tempus lacus enim ac dui.Donec non enim in turpis pulvinar facilisis. Ut felis.</p>
 125
 126                         <p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. <em>Aenean ultricies mi vitae est.</em> Mauris placerat eleifend leo. Quisque sit amet est et sapien ullamcorper pharetra. Vestibulum erat wisi, condimentum sed, <code>commodo vitae</code>, ornare sit amet, wisi. Aenean fermentum, elit eget tincidunt condimentum, eros ipsum rutrum orci, sagittis tempus lacus enim ac dui.Donec non enim in turpis pulvinar facilisis. Ut felis.</p>
 127
 128
 129                         <h3>And an inset list</h3>
 130
 131                                         <ul data-role="listview" data-inset="true">
 132                                                 <li><a href="index.html">Inbox <span class="ui-li-count">12</span></a></li>
 133                                                 <li><a href="index.html">Outbox <span class="ui-li-count">0</span></a></li>
 134                                                 <li><a href="index.html">Drafts <span class="ui-li-count">4</span></a></li>
 135                                                 <li><a href="index.html">Sent <span class="ui-li-count">328</span></a></li>
 136                                                 <li><a href="index.html">Trash <span class="ui-li-count">62</span></a></li>
 137                                         </ul>
 138
 139                         <br />
 140                         <p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. <em>Aenean ultricies mi vitae est.</em> Mauris placerat eleifend leo. Quisque sit amet est et sapien ullamcorper pharetra. Vestibulum erat wisi, condimentum sed, <code>commodo vitae</code>, ornare sit amet, wisi. Aenean fermentum, elit eget tincidunt condimentum, eros ipsum rutrum orci, sagittis tempus lacus enim ac dui.Donec non enim in turpis pulvinar facilisis. Ut felis.</p>
 141
 142                         <p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. <em>Aenean ultricies mi vitae est.</em> Mauris placerat eleifend leo. Quisque sit amet est et sapien ullamcorper pharetra. Vestibulum erat wisi, condimentum sed, <code>commodo vitae</code>, ornare sit amet, wisi. Aenean fermentum, elit eget tincidunt condimentum, eros ipsum rutrum orci, sagittis tempus lacus enim ac dui.Donec non enim in turpis pulvinar facilisis. Ut felis.</p>
 143
 144
 145                         <h3>Embedded form</h3>
 146
 147                         <form action="#" method="get">
 148
 149                                 <div data-role="fieldcontain">
 150                          <label for="name">Text Input:</label>
 151                          <input type="text" name="name" id="name" value=""  />
 152                                 </div>
 153
 154                                 <div data-role="fieldcontain">
 155                                 <label for="textarea">Textarea:</label>
 156                                 <textarea cols="40" rows="8" name="textarea" id="textarea"></textarea>
 157                                 </div>
 158
 159                                 <div data-role="fieldcontain">
 160                                         <label for="slider2">Flip switch:</label>
 161                                         <select name="slider2" id="slider2" data-role="slider">
 162                                                 <option value="off">Off</option>
 163                                                 <option value="on">On</option>
 164                                         </select>
 165                                 </div>
 166
 167                                 <div data-role="fieldcontain">
 168                                         <label for="slider">Slider:</label>
 169                                         <input type="range" name="slider" id="slider" value="0" min="0" max="100"  />
 170                                 </div>
 171
 172
 173                                 <div data-role="fieldcontain">
 174                                         <label for="select-choice-1" class="select">Choose shipping method:</label>
 175                                         <select name="select-choice-1" id="select-choice-1">
 176                                                 <option value="standard">Standard: 7 day</option>
 177                                                 <option value="rush">Rush: 3 days</option>
 178                                                 <option value="express">Express: next day</option>
 179                                                 <option value="overnight">Overnight</option>
 180                                         </select>
 181                                 </div>
 182
 183
 184                         <div class="ui-body ui-body-b">
 185                         <fieldset class="ui-grid-a">
 186                                         <div class="ui-block-a"><button type="submit" data-theme="d">Cancel</button></div>
 187                                         <div class="ui-block-b"><button type="submit" data-theme="b">Submit</button></div>
 188                     </fieldset>
 189                         </div>
 190                 </form>
 191
 192                 <h3>A bit more text</h3>
 193
 194                 <p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. <em>Aenean ultricies mi vitae est.</em> Mauris placerat eleifend leo. Quisque sit amet est et sapien ullamcorper pharetra. Vestibulum erat wisi, condimentum sed, <code>commodo vitae</code>, ornare sit amet, wisi. Aenean fermentum, elit eget tincidunt condimentum, eros ipsum rutrum orci, sagittis tempus lacus enim ac dui.Donec non enim in turpis pulvinar facilisis. Ut felis.</p>
 195
 196
 197
 198
 199                                 </div><!--/content-primary -->
 200
 201                                 <div class="content-secondary">
 202
 203                                         <div data-role="collapsible" data-collapsed="true" data-theme="b" data-content-theme="d">
 204
 205                                                         <h3>More in this section</h3>
 206
 207                                                         <ul data-role="listview" data-theme="c" data-dividertheme="d">
 208
 209                                                                 <li data-role="list-divider">Toolbars</li>
 210                                                                 <li><a href="docs-bars.html">Toolbar basics</a></li>
 211                                                                 <li><a href="docs-headers.html">Header bars</a></li>
 212                                                                 <li><a href="docs-footers.html">Footer bars</a></li>
 213                                                                 <li><a href="docs-navbar.html">Navbars</a></li>
 214                                                                 <li data-theme="a"><a href="bars-fixed.html">Fixed positioning</a></li>
 215                                                                 <li><a href="footer-persist-a.html">Persistent toolbars</a></li>
 216                                                                 <li><a href="bars-themes.html">Theming toolbars</a></li>
 217
 218                                                         </ul>
 219                                         </div>
 220                                 </div>
 221
 222                         </div><!-- /content -->
 223
 224                         <div data-role="footer" data-theme="a" data-position="fixed">
 225                                         <h1>Fixed Footer</h1>
 226                         </div>
 227
 228                         </div><!-- /page -->
 229
 230                         </body>
 231                         </html>