This repository has been archived by the owner on Oct 8, 2021. It is now read-only.
/
docs-lists.html
208 lines (146 loc) · 15.6 KB
/
docs-lists.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>jQuery Mobile Docs - Lists Overview</title>
<link rel="stylesheet" href="../../css/themes/default/jquery.mobile.css" />
<link rel="stylesheet" href="../_assets/css/jqm-docs.css"/>
<script src="../../js/jquery.js"></script>
<script src="../../docs/_assets/js/jqm-docs.js"></script>
<script src="../../js/"></script>
</head>
<body>
<div data-role="page" class="type-interior">
<div data-role="header" data-theme="f">
<h1>Lists</h1>
<a href="../../" data-icon="home" data-iconpos="notext" data-direction="reverse">Home</a>
<a href="../nav.html" data-icon="search" data-iconpos="notext" data-rel="dialog" data-transition="fade">Search</a>
</div><!-- /header -->
<div data-role="content">
<div class="content-primary">
<h2>Listviews</h2>
<ul data-role="controlgroup" data-type="horizontal" class="localnav">
<li><a href="docs-lists.html" data-role="button" data-transition="fade" class="ui-btn-active">Basics</a></li>
<li><a href="lists-options.html" data-role="button" data-transition="fade">Options</a></li>
<li><a href="lists-methods.html" data-role="button" data-transition="fade">Methods</a></li>
<li><a href="lists-events.html" data-role="button" data-transition="fade">Events</a></li>
</ul>
<h2>Basic linked lists</h2>
<p>A listview is coded as a simple unordered list containing linked list items with a <code> data-role="listview"</code> attribute. jQuery Mobile will apply all the necessary styles to transform the list into a mobile-friendly listview with right arrow indicator that fills the full width of the browser window. When you tap on the list item, the framework will trigger a click on the first link inside the list item, issue an Ajax request for the URL in the link, create the new page in the DOM, then kick off a page transition. View the <a href="../api/data-attributes.html">data- attribute reference</a> to see all the possible attributes you can add to listviews.</p>
<p>Here is the HTML markup for a basic linked list.</p>
<pre><code>
<ul data-role="listview" data-theme="b">
<li><a href="acura.html">Acura</a></li>
<li><a href="audi.html">Audi</a></li>
<li><a href="bmw.html">BMW</a></li>
</ul>
</code></pre>
<a href="lists-ul.html" data-role="button" data-icon="arrow-r" data-iconpos="right">Basic list example</a>
<p><strong>Style note on non-inset lists</strong>: all standard, non-inset lists have a -15px margin to negate the 15px of padding on the content area to make lists fill to the edges of the screen. If you add other widgets above or below a list, the negative margin may make these elements overlap so you'll need to add additional spacing in your custom CSS.</p>
<h2>Nested lists</h2>
<p>By nesting child <code>ul</code> or <code>ol</code> inside list items, you can create nested lists. When a list item with a child list is clicked, the framework will show a new page populated with the title of the parent in the header and the list of child elements. These dynamic nested lists are styled with the "b" theme swatch (blue in the default theme) to indicate that you are in a secondary level of navigation. Lists can be nested multiple levels deep and all pages and linking will be automatically handled by the framework. Note that the page of each nested listview is created when the parent page loads and for each nested page the page-events will trigger.</p>
<p>To <a href="../lists/lists-themes.html">set the swatch color</a> of the child listviews, set the <code>data-theme</code> attribute on each list inside.</p>
<a href="lists-nested.html" data-role="button" data-icon="arrow-r" data-iconpos="right">Nested list example</a>
<h2>Numbered lists</h2>
<p>Lists can also be created from ordered lists (<code>ol</code>) which is useful when presenting items that are in a sequence such as search results or a movie queue. When the enhanced markup is applied to the listview, jQuery Mobile will try to first use CSS to add numbers to the list and, if not supported, will fall back to injecting numbers with JavaScript.</p>
<a href="lists-ol.html" data-role="button" data-icon="arrow-r" data-iconpos="right">Numbered list example</a>
<h2>Read-only lists</h2>
<p>Listviews can also be used to display a non-interactive list of items, usually as an inset list. This list is built from an unordered or ordered list that don't have linked list items. The framework styles the list items as buttons like the other list types (see <a href="../lists/lists-themes.html">theming lists</a>), but without a gradient on the background.</p>
<a href="lists-readonly-inset.html" data-role="button" data-icon="arrow-r" data-iconpos="right">Read-only list example</a>
<h2>Split button lists</h2>
<p>In cases where there is more than one possible action per list item, a split button can be used to offer two independently clickable items -- the list item and a small arrow icon in the far right. To make a split list item, simply add a second link inside the <code>li</code> and the framework will add a vertical divider line, style the link as an icon-only arrow button, and set the <code>title</code> attribute of the link to the text of the link for accessibility.</p>
<p>You can set the icon for the right split icon by specifying a <code>data-split-icon</code> attribute on the listview with a <a href="../buttons/buttons-icons.html">icon name</a> you want. The default icon is "arrow-r" but can be configured with the <code>splitIcon</code> <a href="../lists/lists-options.html">listview option</a>. By adding a <code>data-icon</code> attribute to the list item, you can set individual icons for each split. The theme swatch color of the split button defaults to "b" (blue in the default theme) but can be set by specifying a swatch letter with the <code>data-split-theme</code> attribute on listview level or for individual splits with the <code>data-theme</code> attribute on link level.</p>
<a href="lists-split.html" data-role="button" data-icon="arrow-r" data-iconpos="right">Split list example</a>
<h2>List dividers</h2>
<p>List items can be turned into dividers to organize and group the list items. This is done by adding the <code> data-role="list-divider"</code> to any list item. These items are styled with the bar swatch "b" by default (blue in the default theme) but you can specify a theme for dividers by adding the <code>data-divider-theme</code> attribute to the list element (<code>ul</code> or <code>ol</code>) and specifying a theme swatch letter.</p>
<a href="lists-divider.html" data-role="button" data-icon="arrow-r" data-iconpos="right">List divider example</a>
<h2>Autodividers</h2>
<p>A listview can be configured to automatically generate dividers for its items. This is done by adding a <code>data-autodividers="true"</code> attribute to any listview.</p>
<p>By default, the text used to create dividers is the uppercased first letter of either the item's link text (for linked lists) or the item's text (for read-only lists). Alternatively, if you are using formatted list items, you can specify divider text by setting the <code>autodividersSelector</code> option on the listview programmatically. For example, to add a custom selector to the element with <code>id="mylistview"</code>:</p>
<pre><code>
$("#mylistview").listview({
autodividers: true,
// the selector function is passed a <li> element from the listview;
// it should return the appropriate divider text for that <li>
// element as a string
autodividersSelector: function ( li ) {
var out = /* generate a string based on the content of li */;
return out;
}
});
</code></pre>
<p>If new list items are added to the list or removed from it, the dividers are <em>not</em> automatically updated: you should call <code>refresh()</code> on the listview to redraw the autodividers.</p>
<a href="lists-autodividers.html" data-role="button" data-icon="arrow-r" data-iconpos="right">Autodividers example</a>
<h2>Search filter</h2>
<p>jQuery Mobile provides a very easy way to filter a list with a simple client-side search feature. To make a list filterable, simply add the <code>data-filter="true"</code> attribute to the list. The framework will then append a search box above the list and add the behavior to filter out list items that don't contain the current search string as the user types. The input's placeholder text defaults to "Filter items...". To configure the placeholder text in the search input, you can either <a href="../api/globalconfig.html">bind to the <code>mobileinit</code> event</a> and set the <code>$.mobile.listview.prototype.options.filterPlaceholder</code> option to a string of your choosing, or use the data-attribute <code>data-filter-placeholder</code> on your listview. By default the search box will inherit its theme from its parent. The search box theme can be configured using the data-attribute <code>data-filter-theme</code> on your listview.</p>
<a href="lists-search.html" data-role="button" data-icon="arrow-r" data-iconpos="right">Search filter example</a>
<p>If you want to change the way in which list items are filtered, ie fuzzy search or matching from the beginning of the string, you can configure the callback used internally by defining <code>$.mobile.listview.prototype.options.filterCallback</code> during <code>mobileinit</code> or after the widget has been created with <code>$("#mylist").listview('option', 'filterCallback', yourFilterFunction)</code>. Any function defined for the callback will be provided three arguments. First, the text of the current list item, second the value being searched for, and third the list item being filtered. A truthy value will result in a hidden list item. The default callback which filters entries without the <code>searchValue</code> as a substring is described below:
</p>
<pre><code>function( text, searchValue, item ){
return text.toString().toLowerCase().indexOf( searchValue ) === -1;
};</code></pre>
<p>To filter list items by values other than the text, add a <code>data-filtertext</code> attribute to the list item. The value of this attribute will be passed as the first argument to the <code>filterCallback</code> function instead of the text. Alternately you can use an attribute of our choosing as defined on the list item itself.</p>
<a href="lists-search-filtertext.html" data-role="button" data-icon="arrow-r" data-iconpos="right">Hidden data filter example</a>
<h2>Text formatting & counts</h2>
<p>The framework includes text formatting conventions for common list patterns like header/descriptions, secondary information and counts through semantic HTML markup.</p>
<ul>
<li>To add a count indicator to the right of the list item, wrap the number in an element with a class of <code>ui-li-count</code></li>
<li>To add text hierarchy, use headings to increase font emphasis and use paragraphs to reduce emphasis. </li>
<li>Supplemental information can be added to the right of each list item by wrapping content in an element with a class of <code>ui-li-aside</code></li>
</ul>
<a href="lists-count.html" data-role="button" data-icon="arrow-r" data-iconpos="right">List with count bubbles</a>
<a href="lists-formatting.html" data-role="button" data-icon="arrow-r" data-iconpos="right">List with text formatting</a>
<h2>Thumbnails & icons</h2>
<p>To add thumbnails to the left of a list item, simply add an image inside a list item as the first child element. The framework will scale the image to 80 pixels square. To use standard 16x16 pixel icons in list items, add the class of <code>ui-li-icon</code> to the image element.</p>
<a href="lists-thumbnails.html" data-role="button" data-icon="arrow-r" data-iconpos="right">List with thumbnail images</a>
<a href="lists-icons.html" data-role="button" data-icon="arrow-r" data-iconpos="right">List with icon images</a>
<h2>Inset lists</h2>
<p>If lists are embedded in a page with other types of content, an inset list packages the list into a block that sits inside the content area with a bit of margin and rounded corners (theme controlled). By adding the <code> data-inset="true"</code> attribute to the list (ul or ol), applies the inset appearance.</p>
<a href="lists-inset.html" data-role="button" data-icon="arrow-r" data-iconpos="right">Inset list example</a>
<h2>Calling the listview plugin</h2>
<p>You can directly call the listview plugin on any selector, just like any jQuery plugin:</p>
<code>$('#mylist').listview();</code>
<h2>Updating lists</h2>
<p>If you add items to a listview, you'll need to call the <code>refresh()</code> method on it to update the styles and create any nested lists that are added. For example:</p>
<code>$('#mylist').listview('refresh');</code>
<p>Note that the <code>refresh()</code> method only affects <strong>new nodes</strong> appended to a list. This is done for performance reasons. Any list items already enhanced will be ignored by the refresh process. This means that if you change the contents or attributes on an already enhanced list item, these won't be reflected. If you want a list item to be updated, replace it with fresh markup before calling refresh.</p>
<p>If you initially want to hide a list item you can do this by adding a class of <strong><code>ui-screen-hidden</code></strong> to li element. Using this class ensures the corner styling is applied correctly as well as border-bottom on the last visible item.
</div><!--/content-primary -->
<div class="content-secondary">
<div data-role="collapsible" data-collapsed="true" data-theme="b" data-content-theme="d">
<h3>More in this section</h3>
<ul data-role="listview" data-theme="c" data-divider-theme="d">
<li data-role="list-divider">Listviews</li>
<li data-theme="a"><a href="docs-lists.html">List basics & API</a></li>
<li><a href="lists-ul.html">Basic linked list</a></li>
<li><a href="lists-nested.html">Nested list</a></li>
<li><a href="lists-ol.html">Numbered list</a></li>
<li><a href="lists-split.html">Split button list</a></li>
<li><a href="lists-divider.html">List dividers</a></li>
<li><a href="lists-autodividers.html">Autodividers</a></li>
<li><a href="lists-count.html">Count bubble</a></li>
<li><a href="lists-thumbnails.html">Thumbnails</a></li>
<li><a href="lists-icons.html">Icons</a></li>
<li><a href="lists-formatting.html">Content formatting</a></li>
<li><a href="lists-inset.html">Inset styled lists</a></li>
<li><a href="lists-search.html">Search filter bar</a></li>
<li><a href="lists-search-inset.html">Inset search filter bar</a></li>
<li><a href="lists-search-with-dividers.html">Search filter bar with dividers</a></li>
<li><a href="lists-search-filtertext.html">Search filter hidden data</a></li>
<li><a href="lists-readonly.html">Read-only lists</a></li>
<li><a href="lists-readonly-inset.html">Read-only inset lists</a></li>
<li><a href="lists-forms.html">Lists with forms</a></li>
<li><a href="lists-forms-inset.html">Inset lists with forms</a></li>
<li><a href="lists-performance.html">List performance test</a></li>
<li><a href="lists-themes.html">Theming lists</a></li>
</ul>
</div>
</div>
</div><!-- /content -->
<div data-role="footer" class="footer-docs" data-theme="c">
<p>© 2012 jQuery Foundation and other contributors</p>
</div>
</div><!-- /page -->
</body>
</html>