I'm a header
I'm the collapsible content. By default I'm closed, but you can click the header to open me.
diff --git a/entries/collapsibleset.xml b/entries/collapsibleset.xml new file mode 100644 index 00000000..5e319276 --- /dev/null +++ b/entries/collapsibleset.xml @@ -0,0 +1,194 @@ + + +Sets of collapsibles
+jQuery Mobile will visually style a set of collapsibles as a group and will make the set behave like an accordion in that only one collapsible can be open at a time if you wrap the collapsibles in a div that has the attribute data-role="collapsibleset".
By default, all the collapsible sections will be collapsed. To set a section to be open when the page loads, add the data-collapsed="false" attribute to the heading of the section you want expanded.
Here is an example of a
Non-inset
+
+ For full width collapsibles without corner styling add the data-inset="false" attribute to the set.
+
Mini
+
+ For a more compact version that is useful in tight spaces, add the data-mini="true" attribute to the set to create a mini version.
+
Custom icons
+ +The icon displayed when a collapsible is shown or hidden can be overridden by using the data-collapsed-icon and data-expanded-icon attributes. Both the collapsibleset widget and the collapsible widget accepts these attributes. When you set one or both of these attributes on the collapsibleset widget all collapsible widgets that are part of the collapsibleset display the icon specified by the chosen value. You can override the icon displayed by individual collapsible widgets by setting one or both of these attributes on the collapsible widget itself.
+
Icon positioning
+ +The default icon positioning for collapsible headings can be overridden by using the data-iconpos attribute. You can set the attribute either on the collapsibleset to affect all collapsibles in the set, or on an individual collapsible widget to affect only the one widget.
+
Theming collapsible content
+ +The standard data-theme attribute can be used to set the color of each collapsible in a set. To provide a clearer visual grouping of the content with the headers, add the data-content-theme attribute with a swatch letter. This adds a themed background color and border to the content block. For consistent theming, add these attributes to the parent
Theming individual sections
+ +To have individual sections in a group styled differently, add data-theme and data-content-theme attributes to specific collapsibles.
+
The
In the example below, pre-rendered markup for a data-corners="false" is explicitly specified, since the absence of the ui-corner-all class on the container element indicates that the "corners" widget option is to be false. One of the child collapsibles is provided as-is, while the other is pre-rendered.
If you manipulate a data-role="collapsible", so there is no need to manually call .collapsible().
Occasionally, you may want to visually group a set of buttons to form a single block that looks contained like a navigation component. To get this effect, wrap a set of buttons in a container with the data-role="controlgroup" attribute — the framework will create a vertical button group, remove all margins and drop shadows between the buttons, and only round the first and last buttons of the set to create the effect that they are grouped together.
-<div data-role="controlgroup">
- <a href="#" data-role="button">Yes</a>
- <a href="#" data-role="button">No</a>
- <a href="#" data-role="button">Maybe</a>
-</div>
-This will result in the following button group: -
-By adding the data-type="horizontal" attribute to the controlgroup container, you can swap to a horizontal-style group that floats the buttons side-by-side and sets the width to only be large enough to fit the content. (Be aware that these will wrap to multiple lines if the number of buttons or the overall text length is too wide for the screen.)
Horizontal grouped buttons: -
- -Labels
-If you use a controlgroup for input, button or select buttons we recommend wrapping them in a fieldset element that has a legend which acts as the combined label for the group. The label elements of each individual button in the group will be hidden for styling purposes, and are only accessible by screen readers. Using the label as a wrapper around the form element prevents the framework from hiding it, so you have to use the for attribute to associate the label with the input.
The jQuery UI controlgroup widget is bundled in jQuery Mobile with some changes. Thus, its API documentation fully describes its functionality.
+
dialog option provided by the page.dialog extension of the page widget allows you to style a page as a dialog, however, the special navigational handling will be removed. You may also consider implementing dialogs using popup widgets.Any page can be presented as a modal dialog by adding the data-rel="dialog" attribute to the page anchor link. When the "dialog" attribute is applied, the framework adds styles to add rounded corners, margins around the page and a dark background to make the "dialog" appear to be suspended above the page.
-<a href="foo.html" data-rel="dialog">Open dialog</a>
-You can open a dialog programmatically by calling the $.mobile.changePage method:
-
-// Dialog loaded via AJAX
+
Transitions
By default, the dialog will open with a 'pop' transition. Like all pages, you can specify any page transition you want on the dialog by adding the data-transition attribute to the link. To make it feel more dialog-like, we recommend specifying a transition of "pop", "slidedown" or "flip".
Possible values include: fade, pop, flip, turn, flow, slidefade, slide, slideup, slidedown, none.
-
-<a href="foo.html" data-rel="dialog" data-transition="pop">Open dialog</a>
-
+
Closing dialogs
When any link is clicked within a dialog, the framework will automatically close the dialog and transition to the requested page, just as if the dialog were a normal page. Nevertheless, dialogs can also be chained, as explained below under "Chaining Dialogs". Similarly, a link that opens a popup will also leave the dialog in place.
-
+
If the dialog has a header the framework will add a close button at the left side of the header. You can change the position by adding data-close-btn="right" to the dialog container. If you don't want a close button in the header or add a custom close button, you can use data-close-btn="none".
-
+
-
+
To create a "cancel" button in a dialog, just link to the page that triggered the dialog to open and add the data-rel="back" attribute to your link. This pattern of linking to the previous page is also usable in non-JS devices as well.
For JavaScript-generated links, you can simply set the href attribute to "#" and use the data-rel="back" attribute. You can also call the dialog's close() method to programmatically close dialogs, for example: $( ".ui-dialog" ).dialog( "close" ).
@@ -59,9 +61,9 @@ $.mobile.changePage( "#myDialog", { role: "dialog" } );
Dialogs can be styled with different theme swatches, just like any page by adding data-theme attributes to the header, content, or footer containers.
-
+
By default dialogs have rounded corners. The option corners can be set to false by adding data-corners="false" to the dialog container:
-
+
Dialogs appear to be floating above an overlay layer. This overlay adopts the swatch 'a' content color by default, but the data-overlay-theme attribute can be added to the page wrapper to set the overlay to any swatch letter.
@@ -76,7 +78,7 @@ $.mobile.changePage( "#myDialog", { role: "dialog" } );
For the sake of readability, dialogs have a default width of 92.5% and a max-width of 500 pixels. There is also a 10% top margin to give dialogs larger top margin on larger screens, but collapse to a small margin on smartphones. The dialog's inner container is shifted towards the top with 15px to hide the corner styling if a dialog is used as a control sheet (see above). To override these styles, add the following CSS override rule to your stylesheet and tweak as needed:
-
+
jQuery Mobile Example
Dialog
I am a dialog
This method is responsible for performing all jQuery Mobile enhancement. Given a set of DOM elements it will enhance their children with all the widgets available.
+The enhancement is based on each widget's initSelector property. This selector will be used to identify the elements upon which the widget will be instantiated.
You can shield elements and their children from enhancement by adding the attribute data-enhance="false" to an element. This will cause it, and all its children to be ignored by .enhanceWithin(). Unfortunately, checking elements to see whether they are children of an element that has been marked with data-enhance="false" is performance-intensive. Thus, the presence of data-enhance="false" will only be considered if the global flag $.mobile.ignoreContentEnabled is set to true.
Caveat: filterable widgets before checkboxradio widgets are enhanced can cause the checkboxradio widgets to be displayed incorrectly. If this affects you, then you must ensure that the widgets which need to be enhanced early are instantiated before the rest of the widgets. One possibility for accomplishing this is to instantiate your widgets during the page widget's pagebeforecreate event.
Filterable Widget
+The ui-screen-hidden to those children for which a filter callback function provided via the widget's filterCallback option returns true.
Backwards compatibility
+ TheThe filterable widget is a generalization of the listview widget's filter extension that was available in jQuery Mobile 1.3. It retains API compatibility with the listview filter. Its behavior is also made backwards compatible by the following deprecated features:
-
+
- If no source is provided for the
via a data-inputattribute, it will generate a text input and place it before the element.
+ - It provides the
filterPlaceholderoption which sets theplaceholderattribute on the generated text input.
+ - It provides the
filterThemeoption which sets thethemeoption on the generated text input.
+ - If a collapsibleset, selectmenu, controlgroup, or listview widget is instantiated on the element whose children are to be filtered, it synchronizes those widget options with the generated text input that the text input widget also provides (options such as "corners" or "mini"). +
- It provides special handling for listviews:
+
-
+
- When filtering listview items, the default filter callback will not hide list items marked as dividers, however, +
- When filtering listview items, the widget enables the listview widget's
hidedividersoption, which causes the new listview hidedividers extension to automatically hide dividers for categories wherein all items are hidden.
+
+
Setup
+To render the children of an element filterable, perform the following steps: +
-
+
- Create an element that will serve as the source for the
. It can be any element that emits a changesignal and has a value that can be accessed via the jQuery .val() plugin. This is usually a text input. Thewidget reacts to the changesignal by reading the value of the input after a short delay and iterating over all the children to determine whether they should be shown or hidden according to the filter callback provided.
+ - Add the attribute
data-filter="true"to the element whose children will be filtered.
+ - Add the attribute
data-inputto the element whose children will be filtered. The value of the attribute is a string containing a jQuery selector that will return the element to be used as the source for the.
+ - Add the child elements that will be filtered. You may add or remove child elements at any time, however, when you add or remove child elements you should call the
refreshmethod on thewidget, to ensure that the new children are shown or hidden in accordance with the latest input provided by the user. + + Child elements may have the
data-filtertextattribute set. In that case, the default filter callback will hide a given child element only if the value of thedata-filtertextattribute does not contain the string provided by the user. If thedata-filtertextattribute is absent, the child will be hidden if its text content does not contain the string provided by the user. +
+
"Reveal" mode
+The normal initial state of a
You can turn on "reveal" mode by adding the attribute data-filter-reveal="true" to the element whose children will be filtered.
The example below illustrates the behavior of a
Custom filters
+The filterCallback option allows you to set a custom callback. In the example below items are filtered by their ordinal, which can be specified using page printing conventions such as "1,2" or "4-9", or both ("1,2,4-9,12").
= searchValue[ idx ][ 0 ] &&
+ index <= searchValue[ idx ][ 1 ] ) ) {
+ return false;
+ }
+ }
+ }
+
+ return !!searchValue;
+};
+]]>The data-enhanced="true", you instruct the ui-screen-hidden to any children which must initially be hidden due to the initial value of the search input.
Note: If the element whose children are to be filtered is enhanced by another widget as well, such as for example a listview or a controlgroup then you are required to provide pre-rendered markup for the other widget as well, because the attribute data-enhanced="true" will influence the initialization behavior of the other widget as well.
In the example below, pre-rendered markup for a data-filter-reveal="true" is explicitly specified, since the presence of the ui-screen-hidden class on all the children indicates that they are initially hidden. The controlgroup widget containing the children is also pre-rendered, because the data-enhanced="true" attribute applies to the controlgroup widget as much as it does to the
ui parameter contains the list of children that was processed.If you manipulate a refresh() method on it to update the visual styling.
In browsers that support CSS position: fixed (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.
To enable this behavior on a header or footer, add the data-position="fixed" attribute to a jQuery Mobile header or footer element.
Fixed header markup example:
-
-<div data-role="header" data-position="fixed">
- <h1>Fixed Header</h1>
-</div>
- Fixed footer markup example:
-
-<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.
- -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>
- Forms in toolbars
- -While all form elements are now tested to work correctly within static toolbars as of jQuery Mobile 1.1, we recommend extensive testing when using form elements within fixed toolbars or within any position: fixed elements. This can potentially trigger a number of unpredictable issues in various mobile browsers, Android 2.2/2.3 in particular (detailed in Known issues in Android 2.2/2.3, below).
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. The framework now offers true fixed toolbars on many popular platforms, while gracefully degrading non-supporting platforms to static positioning.
Polyfilling older platforms
-The fixed toolbar plugin degrades gracefully in platforms that do not support CSS position:fixed 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.
-
-
- Github code repository with CSS, and JavaScript required for the fixed toolbars polyfill -
- Preview URL using the code in the repo above -
Just include the CSS and JS files after your references to jQuery Mobile and Fixed toolbars will work similarly to jQuery Mobile 1.0 in iOS4.3, with the inclusion of the new API for the 1.1 fixedtoolbar plugin.
- -If you have any improvements to suggest, fork the gist on github and let us know!
- -Known issue with form controls inside fixed toolbars, and programmatic scroll
-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 window.scrollTo 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. This ticket from the Device Bugs project tracker explains this problem in more detail.
Known issues in Android 2.2/2.3
-Android 2.2/2.3's implementation of position: fixed; can, in conjunction with seemingly unrelated styles and markup patterns, cause a number of strange issues, particularly in the case of position: absolute elements inside of position: fixed 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.
-
-
- Form elements elsewhere on the page—select menus in particular—can fail to respond to user interaction when an empty absolute positioned element is placed within a fixed position element. In rare cases—and specific to Android 2.2—this can cause entire pages 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. -
- The above-described issue can also be triggered by an absolute positioned image inside of a fixed position element, but only when that image is using something other than its inherent dimensions. 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. -
- When a
position: fixedelement appears anywhere on a page, most 2D CSS transforms will fail. Oddly, onlytranslatetransforms seem unaffected by this. Even more oddly, this issue is solved by setting a CSSopacityof .9 or below on the parent of the fixed element.
- - Combinations of
position: fixedand overflow properties are best avoided, as both have been known to cause unpredictable issues in older versions of Android OS.
- - Any element that triggers the on-screen keyboard, when placed inside a
position: fixedelement, 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.
-
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.
- -No longer supported: touchOverflowEnabled
-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.
As of jQuery Mobile 1.4.0 the functionality of the fixedtoolbar widget has been moved to the toolbar widget.
+-
$.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.
Flip switches
+The flip switch is an alternative look to the checkbox or the two-option select menu. It can be toggled by a click or a swipe.
+To create a flip switch add the attribute data-role="flipswitch" to a checkbox input or to a select which has two option values.
-
+
-
+
ui-flipswitch: The outermost container for flipswitch. Additionally,ui-flipswitch-activeclass will be applied in case flipswitch is in active +-
+
-
+
ui-flipswitch-on: On state label of flipswitch +
+ -
+
ui-flipswitch-off: Off state label of flipswitch +
+ -
+
ui-flipswitch-input: Input checkbox element for flipswitch +
+
+ -
+
Checkbox-based flipswitch
+Use the following markup to create a flipswitch based on a checkbox input:
+
onText and offText options.
+ Select-based flipswitch
+You can also create a flipswitch based on a select element:
+
select element's option elements. The first option is used for the inactive, "off" state, and the second option is used for the active, "on" state.
+
+ Custom labels
+You can customize the labels displayed by the option elements if the widget is based on a select.
The location of the text inside the two labels is specified manually in the
Depending on your choice of labels, you may also have to provide custom CSS to override the default width for the flipswitch:
+The div around the input. In addition to the original element, the wrapper also contains two span elements where the two labels are stored. The first span is styled as a button with the text for the active state appearing outside the button's bounding box to the left. To make the tabindex="1" attribute to the first span.
In the example below, pre-rendered markup for a data-corners="false" is explicitly specified, since the absence of the ui-corner-all class on the wrapper element indicates that the "corners" widget option is to be false.
If you manipulate a
Footer bar structure
-The footer bar has the same basic structure as the header except it uses the data-role attribute value of footer.
-<div data-role="footer">
- <h4>Footer content</h4>
-</div>
-The footer toolbar will be themed with the "a" swatch by default (black in the default theme) but you can easily set the theme swatch color.
-
The page footer is very similar to the header in terms of options and configuration. The primary difference is that the footer is designed to be less structured than the header to allow more flexibility, so the framework doesn't automatically reserve slots for buttons to the left or right as it does in headers.
-Since footers do not have the same prescriptive markup conventions as headers, we recommend using layout grids or writing custom styles to achieve the design you want.
- -Adding buttons
-Any link or valid button markup added to the footer will automatically be turned into a button. To save space, buttons in toolbars are automatically set to inline styling so the button is only as wide as the text and icons it contains.
-By default, toolbars don't have any padding to accommodate nav bars and other widgets. To include padding on the bar, add a class="ui-bar" to the footer.
-<div data-role="footer" class="ui-bar">
- <a href="index.html" data-role="button" data-icon="plus">Add</a>
- <a href="index.html" data-role="button" data-icon="arrow-u">Up</a>
- <a href="index.html" data-role="button" data-icon="arrow-d">Down</a>
-</div>
-This creates this toolbar with buttons sitting in a row -
- -Note that .ui-bar should not be added to header or footer bars that span the full width of the page, as the additional padding will cause a full-width element to break out of its parent container. To add padding inside of a full-width toolbar, wrap the toolbar's contents in an element and apply the padding to that element.
To group buttons together into a button set, wrap the links in a wrapper with data-role="controlgroup" and data-type="horizontal" attributes.
<div data-role="controlgroup" data-type="horizontal">
-
- This creates a grouped set of buttons: -
- -Adding form elements
-Form elements and other content can also be added to toolbars. Here is an example of a select menu inside a footer bar. We recommend using mini-sized form elements in toolbars by adding the data-mini="true" attribute:
-
Fixed & Persistent footers
-In situations where the footer is a global navigation element, you may want it to appear fixed so it doesn't scroll out of view. It's also possible to make a fixed toolbar persistent so it appears to not move between page transitions. This can be accomplished by using the persistent footer feature included in jQuery Mobile.
-To make a footer persistent between transitions, add the data-id attribute to the footer of all relevant pages and use the same id value for each. For example, by adding data-id="myfooter" to the current page and the target page, the framework will keep the footer anchors in the same spot during the page animation. This effect will only work correctly if the header and footer toolbars are set to data-position="fixed" so they are in view during the transition.
As of jQuery Mobile 1.4.0 the functionality of the footer widget has been moved to the toolbar widget.
+To build a two-column (50/50%) layout, start with a container with a class of ui-grid-a, and add two child containers inside it classed with ui-block-a for the first column and ui-block-b for the second:
-<div class="ui-grid-a">
- <div class="ui-block-a"><strong>I'm Block A</strong> and text inside will wrap</div>
- <div class="ui-block-b"><strong>I'm Block B</strong> and text inside will wrap</div>
-</div><!-- /grid-a -->
-The above markup produces the following content layout:
As you see above, by default grid blocks have no visual styling; they simply present content side-by-side.
Grid classes can be applied to any container. In this next example, we add ui-grid-a to a fieldset, and apply the ui-block classes to the container of each of the two buttons inside to stretch them each to 50% of the screen width:
-<fieldset class="ui-grid-a">
- <div class="ui-block-a"><button type="submit" data-theme="c">Cancel</button></div>
- <div class="ui-block-b"><button type="submit" data-theme="b">Submit</button></div>
-</fieldset>
-Please note that the framework adds left and right margin to buttons in a grid. For a single button you can use a container with class ui-grid-solo and wrap the button in a div with class ui-block-a like the example below. This way the button will get the same margin.
-<div class="ui-grid-a">
- <div class="ui-block-a"><button type="button" data-theme="c">Previous</button></div>
- <div class="ui-block-b"><button type="button" data-theme="c">Next</button></div>
-</div>
-<div class="ui-grid-solo">
- <div class="ui-block-a"><button type="v" data-theme="b">More</button></div>
-</div>
-Theme classes (not data-theme attributes) from the theming system can be added to an element, including grids. On the blocks below, we're adding two classes: ui-bar to add the default bar padding and ui-bar-e to apply the background gradient and font styling for the "e" toolbar theme swatch. For illustration purposes, an inline style="height:120px" attribute is also added to each grid to set each to a standard height.
Theme classes (not data-theme attributes) from the theming system can be added to an element, including grids. On the blocks below, we're adding two classes: ui-bar to add the default bar padding and ui-bar-a to apply the background and font styling for the "a" toolbar theme swatch. For illustration purposes, an inline style="height:120px" attribute is also added to each grid to set each to a standard height.
The other grid layout configuration uses class=ui-grid-b on the parent, and 3 child container elements, each with its respective ui-block-a/b/c class, to create a three-column layout (33/33/33%). Note: These blocks are also styled with theme classes so the grid layout is clearly visible.
-<div class="ui-grid-b">
- <div class="ui-block-a">Block A</div>
- <div class="ui-block-b">Block B</div>
- <div class="ui-block-c">Block C</div>
-</div><!-- /grid-b -->
-This will produce a 33/33/33% grid for our content.
- +And an example of a 3 column grid with buttons inside:
- +Four-column grids
A four-column, 25/25/25/25% grid is created by specifying class=ui-grid-c on the parent and adding a fourth block. Note: These blocks are also styled with theme classes so the grid layout is clearly visible.
Five-column grids
A five-column, 20/20/20/20/20% grid is created by specifying class=ui-grid-d on the parent and adding a fifth block. Note: These blocks are also styled with theme classes so the grid layout is clearly visible.
Multiple row grids
Grids are designed to wrap to multiple rows of items. For example, if you specify a 3-column grid (ui-grid-b) on a container that has nine child blocks, it will wrap to 3 rows of 3 items each. There is a CSS rule to clear the floats and start a new line when the class=ui-block-a is seen so make sure to assign block classes in a repeating sequence (a, b, c, a, b, c, etc.) that maps to the grid type:
Grids in toolbars
- +Grids are helpful for creating layouts within a toolbar. Here's a footer with a 4 column grid.
- +