From 967a374cd34c85d68e8e6d7a90fbcefe6e1ebd96 Mon Sep 17 00:00:00 2001 From: scottjehl Date: Thu, 26 Jan 2012 17:02:16 +0700 Subject: [PATCH] updated documentation on the new fixedtoolbar plugin. --- docs/toolbars/bars-fixed-events.html | 81 +++++++++++++ docs/toolbars/bars-fixed-methods.html | 131 +++++++++++++++++++++ docs/toolbars/bars-fixed-options.html | 157 ++++++++++++++++++++++++++ docs/toolbars/bars-fixed.html | 70 +++++++----- docs/toolbars/bars-fullscreen.html | 3 +- docs/toolbars/bars-themes.html | 1 - docs/toolbars/docs-bars.html | 9 +- docs/toolbars/docs-footers.html | 1 - docs/toolbars/docs-headers.html | 1 - docs/toolbars/docs-navbar.html | 1 - docs/toolbars/footer-persist-a.html | 1 - docs/toolbars/footer-persist-b.html | 1 - docs/toolbars/footer-persist-c.html | 1 - docs/toolbars/index.html | 1 - 14 files changed, 418 insertions(+), 41 deletions(-) create mode 100755 docs/toolbars/bars-fixed-events.html create mode 100755 docs/toolbars/bars-fixed-methods.html create mode 100755 docs/toolbars/bars-fixed-options.html diff --git a/docs/toolbars/bars-fixed-events.html b/docs/toolbars/bars-fixed-events.html new file mode 100755 index 00000000..1fac1950 --- /dev/null +++ b/docs/toolbars/bars-fixed-events.html @@ -0,0 +1,81 @@ + + + + + + jQuery Mobile Framework - Fixed Toolbars + + + + + + + + +
+ +
+ +

Fixed toolbars

+ Home +
+ +
+
+

Fixed toolbars

+ + + +

The fixedtoolbar plugin has the following custom events:

+ +
+ +
create triggered when a select menu is created
+
+ + 

+$( ".selector" ).fixedtoolbar({
+   create: function(event, ui) { ... }
+});		
+
+
+ + +
+ +
+ +
+ +

More in this section

+ + +
+
+ +
+ +
+

Fixed Footer

+
+ +
+ + + \ No newline at end of file diff --git a/docs/toolbars/bars-fixed-methods.html b/docs/toolbars/bars-fixed-methods.html new file mode 100755 index 00000000..79891396 --- /dev/null +++ b/docs/toolbars/bars-fixed-methods.html @@ -0,0 +1,131 @@ + + + + + + jQuery Mobile Framework - Fixed Toolbars + + + + + + + + +
+ +
+ +

Fixed toolbars

+ Home +
+ +
+
+

Fixed toolbars

+ + + + + + + + +

The fixedtoolbar plugin has the following methods:

+ +
+ +
show show the toolbar
+
+ 

+		    $("[data-position='fixed']").fixedtoolbar('show');
+
+ +
+

Note:Prior to version 1.1, the following syntax was used to show the toolbars, but it is no longer supported:

+

+$.mobile.fixedToolbars
+   .show(true);
+
+ + +
+ +
+ +
hide hide the toolbar (if it's not a fullscreen toolbar, it'll toggle back to static positioning, which may or may not be hidden from view depending on scroll)
+
+ 

+$("[data-position='fixed']").fixedtoolbar('hide');
+
+
+ +
toggle calls either the show or the hide method, depending on whether the toolbar is visible.
+
+ 

+$("[data-position='fixed']").fixedtoolbar('toggle');
+
+
+ +
updatePagePadding update the padding (either top or bottom, depending on if the toolbar is a header or a footer) of the page element parent of the toolbar to match the height of the toolbar.
+
+ 

+$("[data-position='fixed']").fixedtoolbar('updatePagePadding');
+
+ +

There is also an updatelayout event that can be used to trigger the toolbars to re-position. Developers who are building dynamic applications that inject content into the current page can also manually trigger this updatelayout event to ensure components on the page update in response to the new content that was just added. This event is used internally in the collapsible and listview filter plugins and is powerful because it's not toolbar-specific -- any widget can be built to listen for the updatelayout event to update the widget in response.

+
+ +
destroy destroy at fixedtoolbar (restore the element to its initial state)
+
+ 

+$("[data-position='fixed']").fixedtoolbar('destroy');
+
+
+ + +
+ + + + + + +
+ +
+ +
+ +

More in this section

+ + +
+
+ +
+ +
+

Fixed Footer

+
+ +
+ + + \ No newline at end of file diff --git a/docs/toolbars/bars-fixed-options.html b/docs/toolbars/bars-fixed-options.html new file mode 100755 index 00000000..18b9d577 --- /dev/null +++ b/docs/toolbars/bars-fixed-options.html @@ -0,0 +1,157 @@ + + + + + + jQuery Mobile Framework - Fixed Toolbars + + + + + + + + +
+ +
+ +

Fixed toolbars

+ Home +
+ +
+
+

Fixed toolbars

+ + + +

The fixedtoolbar plugin has the following options:

+ + +
+ +
visibleOnPageShow boolean
+
+

default: true

+

This determines whether the toolbar is visible or not when its parent page is shown. This option is also exposed as a data attribute: data-visible-on-page-show="false"

+ 
$("[data-role=header]").fixedtoolbar({ visibleOnPageShow: false });
+
+ +
disablePageZoom boolean
+
+

default: true

+

This determines whether user-scaling should be disabled on pages that contain fixed toolbars. This option is also exposed as a data attribute: data-disable-page-zoom="false"

+ 
$("[data-role=header]").fixedtoolbar({ disablePageZoom: false });
+
+ +
transition string
+
+

default: "slide" (which ends up using slideup and slidedown)

+

The transition that should be used for showing and hiding a fixed toolbar. Possible values are "none", "fade", and "slide" (or you can write a CSS transition of your own and use that too). This option is also exposed as a data attribute: data-transition=""fade""

+ 
$("[data-role=header]").fixedtoolbar({ transition: "fade" });
+
+ +
fullscreen boolean
+
+

default: false

+

Fullscreen 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. This page demonstrates toolbars that use the fullscreen option. This option is also exposed as a data attribute: data-fullscreen=""true""

+ 
$("[data-role=header]").fixedtoolbar({ fullscreen: true });
+ +

Note:While the data-attribute syntax for this option has not changed, it is now only supported on the toolbar element itself, and not the page element.

+ +
+ +
tapToggle boolean
+
+

default: true

+

Enable or disable the user's ability to toggle toolbar visibility with a tap on the screen (or a click, for mouse users). This option is also exposed as a data attribute: data-tap-toggle=""true""

+ 
$("[data-role=header]").fixedtoolbar({ tapToggle: true });
+ +
+

Note: This behavior was formerly configurable as follows, but as of version 1.1 this syntax is no longer supported: +

	
+$.mobile.fixedToolbars
+   .setTouchToggleEnabled(false);
+
+ +
+ +
+ +
updatePagePadding boolean
+
+

default: true

+

Since toolbars can vary in height depending on the content they contain, this option automatically updates the padding on the page element to ensure that fixed toolbars have adequate space in the document when they are statically positioned, and when scrolled to the top or bottom of the page. When enabled, the padding updates during many operations, such as pageshow, during page transitions, and on resize and orientationchange. As an optimization, we would recommend that you consider disabling this option and adding a rule to your CSS to set the padding of the page div to match the EM height of your toolbars, such as .ui-page-header-fixed { padding-top: 4.5em; }. This option is also exposed as a data attribute: data-update-page-paddinge=""false""

+ 
$("[data-role=header]").fixedtoolbar({ updatePagePadding: false });
+
+ + +
supportBlacklist function
+
+

default: function that returns a boolean value

+

CSS position: fixed support is very difficult to test; in fact, at the time of version 1.1 release, there was no known way to reasonably test for fixed support without turning up false positives or negatives in certain popular browsers. This option is a function that attempts to opt-out some popular platforms that are known to be troublesome with position: fixed . Often, these platforms support position: fixed partially, which can be worse than not supporting it at all. If overriding this option with your own blacklist logic, you simply need to provide a function that returns a true or false result when called upon initialization. You must set it on mobileinit, so that it applies when the plugin is initially created.

+ 

+$( document ).bind("mobileinit", function(){
+  $.mobile.fixedtoolbar.prototype.options.supportBlacklist = function(){
+    var result;
+    // logic to determine whether result should be true or false
+    return result;
+  };
+})
+
+ + +
initSelector CSS selector string
+
+

default: ":jqmData(position='fixed')"

+

This is used to define the selectors (element types, data roles, etc.) that will automatically be initialized as fixed toolbars. To change which elements are initialized, bind this option to the mobileinit event:

+ 
$( document ).bind( "mobileinit", function(){
+	$.mobile.fixedtoolbar.prototype.options.initSelector = ".myselector";
+});
+
+
+ + + +
+ + +
+ +
+ +
+ +

More in this section

+ + +
+
+ +
+ +
+

Fixed Footer

+
+ +
+ + + \ No newline at end of file diff --git a/docs/toolbars/bars-fixed.html b/docs/toolbars/bars-fixed.html index 354e9159..813daecc 100755 --- a/docs/toolbars/bars-fixed.html +++ b/docs/toolbars/bars-fixed.html @@ -23,36 +23,55 @@

Fixed toolbars

-

This is a demo of the "fixed" headers and footers used in the jQuery Mobile framework. The page content flows naturally, allowing us to take advantage of native scrolling instead of a scripting a faux-scrolling workaround. The header and footer divs are right in the flow of the document, but whenever they are out of view the framework will dynamically re-position them into view if the browser supports this feature, otherwise they will simply stay inline.

-

To enable this behavior on a header or footer, add the data-position="fixed" attribute to the toolbar container.

- + + + + +

In browsers that support CSS position: fixed, (generally, most desktop browsers, iOS5+, Android 2.2+, BlackBerry 6, and more), 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 fall back to static, inline positiong in the page.

+ +

To enable this behavior on a header or footer, add the data-position="fixed" attribute to a jQuery Mobile header or footer element.

+ +

A fixed header toolbar

+ 
	
+<div data-role="header" data-position="fixed">
+	<h1>Fixed Header!</h1>
+</div>
+
+ +

A fixed footer toolbar

+ 
	
+<div data-role="footer" data-position="fixed">
+	<h1>Fixed Footer!</h1>
+</div>
+
+ +

Fullscreen Toolbars

+

Fullscreen 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. This page demonstrates toolbars that use the fullscreen option.

+ +

To enable this option on a fixed header or footer, add the data-fullscreen attribute to the element.

+ + 
	
+<div data-role="header" data-position="fixed" data-fullscreen="true">
+	<h1>Fixed Header!</h1>
+</div>
+
+ -

Tap to toggle visibility

-

To toggle the visibility of fixed toolbars, tap the screen. For example, if the fixed toolbars are visible, tap the screen to hide the toolbars and take full advantage of the screen real estate for content. Tapping again will bring the toolbars back into view.

-

It's possible to turn off the the tap to toggle visibility behavior like this:

-

-$.mobile.fixedToolbars
-   .setTouchToggleEnabled(false);
-
-

Updating toolbar positioning

-

If the height of the page changes, either through dynamic injection of markup, or by widgets that hide or collapse content, it can throw off the dynamic positioning of the toolbars. To manually tell the toolbars to re-position themselves then fade in, use $.mobile.fixedToolbars.show();. To have them appear immediately without the fade:

-

-$.mobile.fixedToolbars
-   .show(true);
-
- -

There is also an updatelayout event that can be used to trigger the toolbars to re-position. Developers who are building dynamic applications that inject content into the current page can also manually trigger this updatelayout event to ensure components on the page update in response to the new content that was just added. This event is used internally in the collapsible and listview filter plugins and is powerful because it's not toolbar-specific -- any widget can be built to listen for the updatelayout event to update the widget in response.

+

Changes in jQuery Mobile 1.1

+

Prior to version 1.1, jQuery Mobile used dynamically re-positioned toolbars for the fixed header effect because very few mobile browsers supported the position:fixed 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, and now the framework offers true fixed toolbars on many popular platforms, while gracefully degrading non-supporting platforms to static positioning.

-

Known limitations

+
+

No longer supported: touchOverflowEnabled

-

jQuery Mobile uses dynamically re-positioned toolbars for the fixed header effect because very few mobile browsers support the position:fixed CSS property. Although our fixed toolbar feature works fairly well, there are a number of technical limitations that can cause the toolbars to appear to scroll with the page. Most of these rendering issues are due to the fact many mobile platforms (iOS, Android, etc.) essentially take a static screenshot of the page and display this image during scrolling instead of the actual rendered HTML. This improves scrolling performance, but when scrolling happens quickly, the toolbars will be "burned" into the page screenshot before our script can hide them so they appear to scroll with the page. We have optimized this as much as we possibly can, but there are going to be situations where fixed toolbars won't work perfectly due to browser limitations, so this is important to note when considering whether to use this feature.

- -

True fixed toolbars: touchOverflowEnabled

- -

In order to achieve true fixed toolbars, a browser needs to either support position:fixed or overflow:auto. Fortunately, this support is coming to mobile platforms so we can achieve this with web standards. In jQuery Mobile, we have added a global feature called touchOverflowEnabled that leverages the overflow:auto CSS property on supported platforms like iOS5. When enabled, the framework wraps each page in a container with it's own internal scrolling. This allows us to position the toolbars outside the scrolling body so they truly stay fixed in place at all times. Learn more about this feature on the global options page or demo this feature (currently iOS5 only, other browsers will fall back to dynamically re-positioned fixed toolbars).

- +

Prior to jQuery Mobile 1.1, true fixed toolbar support was contingent on native browser support for the CSS property overflow-scrolling: touch, 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 $.support and we have no plans to remove that test at this time.

+
@@ -149,7 +168,6 @@ $.mobile.fixedToolbars
  • Footer bars
  • Navbars
  • Fixed positioning
    • -
  • Fullscreen positioning
  • Persistent footer navbar
  • Theming toolbars
    • diff --git a/docs/toolbars/bars-fullscreen.html b/docs/toolbars/bars-fullscreen.html index 1d173dc7..dd95cf11 100755 --- a/docs/toolbars/bars-fullscreen.html +++ b/docs/toolbars/bars-fullscreen.html @@ -45,8 +45,7 @@
  • Header bars
  • Footer bars
  • Navbars
    • -
  • Fixed positioning
    • -
  • Fullscreen positioning
    • +
  • Fixed positioning
  • Persistent footer navbar
  • Theming toolbars
    • diff --git a/docs/toolbars/bars-themes.html b/docs/toolbars/bars-themes.html index 605d2b41..61956136 100644 --- a/docs/toolbars/bars-themes.html +++ b/docs/toolbars/bars-themes.html @@ -155,7 +155,6 @@
  • Footer bars
  • Navbars
  • Fixed positioning
    • -
  • Fullscreen positioning
  • Persistent footer navbar
  • Theming toolbars
    • diff --git a/docs/toolbars/docs-bars.html b/docs/toolbars/docs-bars.html index d0874021..22c52b60 100755 --- a/docs/toolbars/docs-bars.html +++ b/docs/toolbars/docs-bars.html @@ -39,11 +39,11 @@

    Header and footers can be positioned on the page in a few different ways. By default, the toolbars use the "inline" positioning mode. In this mode, the headers and footer sit in the natural document flow (the default HTML behavior), which ensures that they are visible on all devices, regardless of JavaScript and CSS positioning support.

    -

    A "fixed" positioning mode provides the convenience of static toolbars without the drawbacks of implementing faux-scrolling in JavaScript. The toolbars start in their natural positions on the page, like the "inline" mode, but when a bar scrolls out of the viewport, the framework animates the bar back into view by dynamically re-positioning the bar to the top or bottom of the viewport.

    -

    At any time, tapping the screen will toggle the visibility of the fixed toolbars: tapping the page when the toolbars aren't visible brings them into view, tapping again hides them until you tap again. This gives users the option to hide the toolbars until needed to maximize screen real estate.

    -

    To set this behavior on a header or footer, add the data-position="fixed" attribute to the toolbar container.

    +

    A "fixed" positioning mode fixes the toolbars to either the top or bottom of the viewport on browsers that support CSS fixed positioning (generally, most desktop browsers, iOS5+, Android 2.2+, BlackBerry 6, and more). In browsers that don't support fixed positioning, the toolbars will fall back to static, inline positiong in the page.

    +

    When tap-toggling is enabled, tapping the screen will toggle the visibility of the fixed toolbars: tapping the page when the toolbars aren't visible brings them into view, tapping again hides them until you tap again. This gives users the option to hide the toolbars until needed to maximize screen real estate. One caveat is that fixed toolbars never truly hide, but toggle between fixed and static positioning. This means that if you're at the top of a page, you can't tap-toggle a header toolbar out of view, as it instead toggles into its spot in the document flow at the top of the page. The same goes for fixed footers when scrolled to the very bottom of a document.

    +

    To set this behavior on a header or footer, add the data-position="fixed" attribute to the header or footer element.

    -

    A "fullscreen" position mode works just like the fixed mode except that the toolbars aren't shown at the top and bottom of the page and only appear when the page is clicked. This is useful for immersive apps like photo or video viewers where you want the content to fill the whole screen and toolbars can be summoned to appear by tapping the screen. Keep in mind that the toolbars in this mode will sit over page content so this is best used for specific situations.

    +

    A "fullscreen" position mode works just like the fixed mode except that the toolbars overlay the page content, rather than reserving a place in the document when not in fixed mode. This is useful for immersive apps like photo or video viewers where you want the content to fill the whole screen and toolbars can be hidden or summoned to appear by tapping the screen. Keep in mind that the toolbars in this mode will sit over page content so this is best used for specific situations.

    @@ -63,7 +63,6 @@
  • Footer bars
  • Navbars
  • Fixed positioning
    • -
  • Fullscreen positioning
  • Persistent footer navbar
  • Theming toolbars
    • diff --git a/docs/toolbars/docs-footers.html b/docs/toolbars/docs-footers.html index 5e9c1acc..c949619a 100755 --- a/docs/toolbars/docs-footers.html +++ b/docs/toolbars/docs-footers.html @@ -132,7 +132,6 @@
  • Footer bars
  • Navbars
  • Fixed positioning
    • -
  • Fullscreen positioning
  • Persistent footer navbar
  • Theming toolbars
    • diff --git a/docs/toolbars/docs-headers.html b/docs/toolbars/docs-headers.html index 551314cf..82bf9e1a 100644 --- a/docs/toolbars/docs-headers.html +++ b/docs/toolbars/docs-headers.html @@ -167,7 +167,6 @@
  • Footer bars
  • Navbars
  • Fixed positioning
    • -
  • Fullscreen positioning
  • Persistent footer navbar
  • Theming toolbars
    • diff --git a/docs/toolbars/docs-navbar.html b/docs/toolbars/docs-navbar.html index f841cf8b..5365a2ad 100755 --- a/docs/toolbars/docs-navbar.html +++ b/docs/toolbars/docs-navbar.html @@ -296,7 +296,6 @@
  • Footer bars
  • Navbars
  • Fixed positioning
    • -
  • Fullscreen positioning
  • Persistent footer navbar
  • Theming toolbars
    • diff --git a/docs/toolbars/footer-persist-a.html b/docs/toolbars/footer-persist-a.html index 2d25cf34..2566162f 100755 --- a/docs/toolbars/footer-persist-a.html +++ b/docs/toolbars/footer-persist-a.html @@ -87,7 +87,6 @@
  • Footer bars
  • Navbars
  • Fixed positioning
    • -
  • Fullscreen positioning
  • Persistent footer navbar
  • Theming toolbars
    • diff --git a/docs/toolbars/footer-persist-b.html b/docs/toolbars/footer-persist-b.html index 433ad887..4de0b4b8 100755 --- a/docs/toolbars/footer-persist-b.html +++ b/docs/toolbars/footer-persist-b.html @@ -111,7 +111,6 @@
  • Footer bars
  • Navbars
  • Fixed positioning
    • -
  • Fullscreen positioning
  • Persistent footer navbar
  • Theming toolbars
    • diff --git a/docs/toolbars/footer-persist-c.html b/docs/toolbars/footer-persist-c.html index c550ea84..e214e8b4 100755 --- a/docs/toolbars/footer-persist-c.html +++ b/docs/toolbars/footer-persist-c.html @@ -96,7 +96,6 @@
  • Footer bars
  • Navbars
  • Fixed positioning
    • -
  • Fullscreen positioning
  • Persistent footer navbar
  • Theming toolbars
    • diff --git a/docs/toolbars/index.html b/docs/toolbars/index.html index 9ddcafae..579a9b39 100755 --- a/docs/toolbars/index.html +++ b/docs/toolbars/index.html @@ -30,7 +30,6 @@
  • Footer bars
  • Navbars
  • Fixed positioning
    • -
  • Fullscreen positioning
  • Persistent footer navbar
  • Theming toolbars