jQuery Mobile Tutorial: Displaying lists
What Will I Learn?
I have described in the previous tutorial the minimal structure of each of our windows. This tutorial allows us to study how to specify a more elaborate content in them, in particular by using lists.
Requirements
jQuery Mobile Framework https://jquerymobile.com/
Difficulty
Intermediate
Tutorial Contents
- A simple list
- A list containing links
- A numbered list with links
- Insert separators in lists
- Search in a list
- Display a counter in a list item
- Include a 80x80 image in list items
- Include a 20x15 image in list items
- Custom lists
- Using CSS themes
Curriculum
jQuery Mobile Tutorial: Displaying lists
I have described in the previous tutorial the minimal structure of each of our windows. This tutorial allows us to study how to specify a more elaborate content in them, in particular by using lists. Lists are a basic element for displaying on mobile devices, due to the small size of these (particularly smartphones).
A simple list
To view a list of items, <ul> or <ol> elements are used containing list items <li>. The data-role="listview" attribute specified in the tag <ul> or <ol> allows you to style the list according to the conventions defined by jQuery Mobile.
A list of items displayed according to the jQuery Mobile conventions
<!DOCTYPE html> <html> <head> <meta name=viewport content="user-scalable=no,width=device-width" /> <link rel=stylesheet href=jquery.mobile/jquery.mobile.css /> <script src=jquery.js></script> <script src=jquery.mobile/jquery.mobile.js></script></head>
<body>
<div data-role=page id=home> <div data-role=header> <h1>Home</h1> </div>
<div data-role=content> <h3> Elements in a list</h3> <ul data-role=listview> <li> Element 1 </li> <li> Element 2 </li> <li> Element 3 </li> <li> Element 4 </li> <li> Element 5 </li> </ul> </div></div>
</body></html>If the attribute data-role="listview" is not specified, the list appears but does not take advantage of CSS styles defined by jQuery Mobile:
A list containing links
Suppose we want to display a list of menus for our application. Each list item is a link to another window (located in the same HTML page or not). We then write:
A list containing links to other windows
<!DOCTYPE html> <html> <head> <meta name=viewport content="user-scalable=no,width=device-width" /> <link rel=stylesheet href=jquery.mobile/jquery.mobile.css /> <script src=jquery.js></script> <script src=jquery.mobile/jquery.mobile.js></script></head>
<body>
<div data-role=page id=home> <div data-role=header> <h1>Home</h1> </div>
<div data-role=content> <h3> Main menu</h3> <ul data-role=listview> <li><a href=#win1> Window 1 </a></li> <li><a href=#win2> Window 2 </a></li> </ul> </div></div>
<div data-role=page id=win1 data-add-back-btn=true> <div data-role=header> <h1>Window 1</h1> </div>
<div data-role=content> <p> Window content 1 </p> </div></div>
<div data-role=page id=win2 data-add-back-btn=true> <div data-role=header> <h1>Window 2</h1> </div>
<div data-role=content> <p> Window content 2 </p> </div></div>
</body></html>Links to other windows are provided in each of the <li> tags. The window appears as follows:
jQuery Mobile increased the height of each list item (so that we can more easily select on the touch screen), and added to the right of each of them an arrow icon pointing to the right (symbolizing that another window appears when you click on the list item). Of course, if you click on each element of the list, the corresponding window appears.
A numbered list with links
This example is a continuation of the previous example. We want to specify before each list item a number (from 1). Simply replace the <ul> tag with a <ol> tag.
A numbered list containing links to other windows
<!DOCTYPE html> <html> <head> <meta name=viewport content="user-scalable=no,width=device-width" /> <link rel=stylesheet href=jquery.mobile/jquery.mobile.css /> <script src=jquery.js></script> <script src=jquery.mobile/jquery.mobile.js></script></head>
<body>
<div data-role=page id=home> <div data-role=header> <h1>Home</h1> </div>
<div data-role=content> <h3> Main menu</h3> <ol data-role=listview> <li><a href=#win1> Window 1 </a></li> <li><a href=#win2> Window 2 </a></li> </ol> </div></div>
<div data-role=page id=win1 data-add-back-btn=true> <div data-role=header> <h1>Window 1</h1> </div>
<div data-role=content> <p> Window content 1 </p> </div></div>
<div data-role=page id=win2 data-add-back-btn=true> <div data-role=header> <h1>Window 2</h1> </div>
<div data-role=content> <p> Window content 2 </p> </div></div>
</body></html>The index of the item in the list was inserted directly before the element content.
Insert separators in lists
It is often useful to group under the same title some items in a list, allowing aerate the presentation of the list for users. For this, we insert elements of separation in the list, indicating the data-role="list-divider" attribute.
A menu with separators
<!DOCTYPE html> <html> <head> <meta name=viewport content="user-scalable=no,width=device-width" /> <link rel=stylesheet href=jquery.mobile/jquery.mobile.css /> <script src=jquery.js></script> <script src=jquery.mobile/jquery.mobile.js></script></head>
<body>
<div data-role=page id=home> <div data-role=header> <h1>Home</h1> </div>
<div data-role=content> <h3> Main menu</h3> <ul data-role=listview> <li data-role=list-divider>Menu 1</li> <li><a href=#win1> Window 1 </a></li> <li data-role=list-divider>Menu 2</li> <li><a href=#win2> Window 2 </a></li> </ul> </div></div>
<div data-role=page id=win1 data-add-back-btn=true> <div data-role=header> <h1>Window 1</h1> </div>
<div data-role=content> <p> Window content 1 </p> </div></div>
<div data-role=page id=win2 data-add-back-btn=true> <div data-role=header> <h1>Window 2</h1> </div>
<div data-role=content> <p> Window content 2 </p> </div></div>
</body></html>The separation elements were styled in a blue background automatically, through the data-role="list-divider" attribute for these items. If one does not have this attribute, it would then display a more conventional (and less useful ...)
Search in a list
When a list has many elements, it can be useful to search for particular items in it. It then indicates the data-filter="true" attribute on the <ul> or <ol>.
Search in a list
<!DOCTYPE html> <html> <head> <meta name=viewport content="user-scalable=no,width=device-width" /> <link rel=stylesheet href=jquery.mobile/jquery.mobile.css /> <script src=jquery.js></script> <script src=jquery.mobile/jquery.mobile.js></script></head>
<body>
<div data-role=page id=home> <div data-role=header> <h1>Home</h1> </div>
<div data-role=content> <h3> Elements in a list</h3> <ul data-role=listview data-filter=true> <li> Element 1 </li> <li> Element 2 </li> <li> Element 3 </li> <li> Element 4 </li> <li> Element 5 </li> </ul> </div></div>
</body></html>A search box is automatically inserted by jQuery Mobile in the window for entering a search string in the list. Introduce the word "1" in the field, in order to search all items containing that number. Upon validation of the entered text, the list refreshes with the elements containing this text:
Display a counter in a list item
jQuery Mobile can easily display a value in a list item, as a small circle containing the value. This can be used for example to indicate the number of messages received by a user.To achieve this it is enough that the list item includes a <span> element with the ui-li-count CSS class. This CSS class is defined by jQuery Mobile and allows you to style the element that has the required form. The content of this <span> element indicates the value that will be displayed in the circle. This value can be any text (numbers or letters).
Use a counter in the list items
<!DOCTYPE html> <html> <head> <meta name=viewport content="user-scalable=no,width=device-width" /> <link rel=stylesheet href=jquery.mobile/jquery.mobile.css /> <script src=jquery.js></script> <script src=jquery.mobile/jquery.mobile.js></script></head>
<body>
<div data-role=page id=home> <div data-role=header> <h1>Home</h1> </div>
<div data-role=content> <h3> Main menu</h3> <ul data-role=listview> <li><a href=#win1> Window 1 </a> <span class=ui-li-count>2</span></li> <li><a href=#win2> Window 2 </a> <span class=ui-li-count>Many</span></li> </ul> </div></div>
<div data-role=page id=win1 data-add-back-btn=true> <div data-role=header> <h1>Window 1</h1> </div>
<div data-role=content> <p> Window content 1 </p> </div></div>
<div data-role=page id=win2 data-add-back-btn=true> <div data-role=header> <h1>Window 2</h1> </div>
<div data-role=content> <p> Window content 2 </p> </div></div>
</body></html>The circles come from the ui-li-count class of <span> elements included in the <li> list items, while the arrows on the right are due to <a> links included in each list item.
Include a 80x80 image in list items
jQuery Mobile makes it easy to include a picture at the beginning of a list item. The image is displayed on a maximum height and width of 80 pixels. Text can be displayed to the right of the image, usually one or two lines.
Images in list items
<!DOCTYPE html> <html> <head> <meta name=viewport content="user-scalable=no,width=device-width" /> <link rel=stylesheet href=jquery.mobile/jquery.mobile.css /> <script src=jquery.js></script> <script src=jquery.mobile/jquery.mobile.js></script></head>
<body>
<div data-role=page id=home> <div data-role=header> <h1>Home</h1> </div>
<div data-role=content> <h3> Main menu</h3> <ul data-role=listview> <li> <img src=images/html.jpg /> <h1> HTML & CSS</h1> <p> Rufu</p> </li> <li> <img src="images/j2ee.jpg" /> <h3>J2EE</h3> <p> Rufu</p> </li> <li> <img src="images/jquery.jpg" /> <h3>JQuery & jQuery UI</h3> <p> Rufu</p> </li> </ul> </div></div>
</body></html>The images are positioned at the beginning of each <li>. Then the elements associated with the text are also inserted. By using a title element (here <h1>) and a neutral element (here <p>) allows you to provide graciously information in the window.
Note that the images reached a maximum height in each list item. Similarly, <h1> and <p> corresponding to the text have been styled according to the conventions defined by jQuery Mobile.It is also possible to make these clickable list items. For that we surround the contents of each <li> list item with a <a> link:
Make clickable list items
<!DOCTYPE html> <html> <head> <meta name=viewport content="user-scalable=no,width=device-width" /> <link rel=stylesheet href=jquery.mobile/jquery.mobile.css /> <script src=jquery.js></script> <script src=jquery.mobile/jquery.mobile.js></script></head>
<body>
<div data-role=page id=home> <div data-role=header> <h1>Home</h1> </div>
<div data-role=content> <h3> Main menu</h3> <ul data-role=listview> <li> <a href=#> <img src=images/html.jpg /> <h1> HTML & CSS</h1> <p> Rufu</p> </a> </li> <li> <a href=#> <img src="images/j2ee.jpg" /> <h3>J2EE</h3> <p> Rufu</p> </a> </li> <li> <a href=#> <img src="images/jquery.jpg" /> <h3>JQuery & jQuery UI</h3> <p> Rufu</p> </a> </li> </ul> </div></div>
</body></html>Note that the links have their href attribute value set to "#", to stay in the same window when clicked (windows to which these links lead do not need to be defined).
Include a 20x15 image in list items
Unlike the previous example, the original image size should now be imposed, which must not exceed 20 pixels wide and 15 pixels high (if not, the frame is not harmonious in the list element). This is done using the ui-li-icon CSS class applied to the <img> element.
Images 20x15 pixels in list items
<!DOCTYPE html> <html> <head> <meta name=viewport content="user-scalable=no,width=device-width" /> <link rel=stylesheet href=jquery.mobile/jquery.mobile.css /> <script src=jquery.js></script> <script src=jquery.mobile/jquery.mobile.js></script></head>
<body>
<div data-role=page id=home> <div data-role=header> <h1>Home</h1> </div>
<div data-role=content> <h3> Main menu</h3> <ul data-role="listview"> <li> <a href=#> Black 20x15 pixels image <img src="images/black.jpg" class=ui-li-icon> </a> </li> <li> <a href=#> Gray 20x15 pixels image <img src="images/gray.jpg" class=ui-li-icon> </a> </li> </ul> </div></div>
</body></html>The use of the ui-li-icon CSS class on the <img> elements allows harmonious arrangement of displayed items. If we remove this class in the CSS <img> elements, we get a display similar to the previous example:
The list items were positioned on a height of 80 pixels, and as we insert an image that does not reach this height, the display is ugly.
Custom lists
Change the icon displayed in the lists
When a <a> link is included in a <li> list item, it appears for the moment an arrow icon pointing to the right, at the right of the list item (see previous example) . This icon is the one displayed by default jQuery Mobile. It is possible to view a different one, or even remove it from the display.
In the previous example, modify each <li> element by adding the data-icon="delete" attribute to display a cross instead of the usual arrow:
Display a cross instead of the arrow in the list items
<!DOCTYPE html> <html> <head> <meta name=viewport content="user-scalable=no,width=device-width" /> <link rel=stylesheet href=jquery.mobile/jquery.mobile.css /> <script src=jquery.js></script> <script src=jquery.mobile/jquery.mobile.js></script></head>
<body>
<div data-role=page id=home> <div data-role=header> <h1>Home</h1> </div>
<div data-role=content> <h3> Main menu</h3> <ul data-role=listview> <li data-icon=delete> <a href=#> <img src=images/html.jpg /> <h1> HTML & CSS</h1> <p> Rufu</p> </a> </li> <li data-icon=delete> <a href=#> <img src="images/j2ee.jpg" /> <h3>J2EE</h3> <p> Rufu</p> </a> </li> <li data-icon=delete> <a href=#> <img src="images/jquery.jpg" /> <h3>JQuery & jQuery UI</h3> <p> Rufu</p> </a> </li> </ul> </div></div>
</body></html>Note that the use of a <a> link is essential here, because it is his presence that allows the display of the icon. If you omit it, you get the display of a list item without icon (even if the data-icon attribute is present).
A cross symbolizing the ability to delete the item replaced the traditional right arrow. Other icons are available in jQuery Mobile, simply by indicating the value for the data-icon attribute:
We will see that the icons are not used only for list items, but can also be used for example in the buttons.
Remove the icon displayed in the lists
The case treated here concerns the removal of the icon in the list items, but keeping the <a> link in each element. It is known that the inclusion of a link automatically inserts an icon to the right of the item. How to remove?
The removal of the icon in a list item is done using the data-icon attribute set to "false" (in the corresponding list item).
For example with the above list, it says not to display the icon for the second item on the list:
Remove the icon for the second list item
<!DOCTYPE html> <html> <head> <meta name=viewport content="user-scalable=no,width=device-width" /> <link rel=stylesheet href=jquery.mobile/jquery.mobile.css /> <script src=jquery.js></script> <script src=jquery.mobile/jquery.mobile.js></script></head>
<body>
<div data-role=page id=home> <div data-role=header> <h1>Home</h1> </div>
<div data-role=content> <h3> Main menu</h3> <ul data-role=listview> <li data-icon=delete> <a href=#> <img src=images/html.jpg /> <h1> HTML & CSS</h1> <p> Rufu</p> </a> </li> <li data-icon=false> <a href=#> <img src="images/j2ee.jpg" /> <h3>J2EE</h3> <p> Rufu</p> </a> </li> <li data-icon=delete> <a href=#> <img src="images/jquery.jpg" /> <h3>JQuery & jQuery UI</h3> <p> Rufu</p> </a> </li> </ul> </div></div>
</body></html>The second element of the list no longer has an icon on the right side of the list item.
Display lists with rounded edges
For now, all the lists were shown with rectangular edges. jQuery Mobile can also display them with rounded edges, using the data-inset="true" attribute set to the <ul> or <ol> associated with the list.
Lists with rounded edges
<!DOCTYPE html> <html> <head> <meta name=viewport content="user-scalable=no,width=device-width" /> <link rel=stylesheet href=jquery.mobile/jquery.mobile.css /> <script src=jquery.js></script> <script src=jquery.mobile/jquery.mobile.js></script></head>
<body>
<div data-role=page id=home> <div data-role=header> <h1>Home</h1> </div>
<div data-role=content> <h3> List 1</h3> <ul data-role=listview data-inset=true> <li> Element 1 </li> <li> Element 2 </li> <li> Element 3 </li> <li> Element 4 </li> <li> Element 5 </li> </ul> <h3> List 2</h3> <ul data-role=listview data-inset=true> <li> Element 1 </li> <li> Element 2 </li> <li> Element 3 </li> <li> Element 4 </li> <li> Element 5 </li> </ul> </div></div>
</body></html>Both lists are shown here with rounded edges due to the positioning of the data-inset attribute to true on each list. This feature is available for all lists that we have previously displayed, in particular those that contain links and images.
Position the text right into the list items
For now, the text is displayed in the list item on the left part of it. You can display it on the right side, inserting the text in an element using the ui-li-aside CSS class, himself included in an <a> element.
Position the text of the list item on the right
<!DOCTYPE html> <html> <head> <meta name=viewport content="user-scalable=no,width=device-width" /> <link rel=stylesheet href=jquery.mobile/jquery.mobile.css /> <script src=jquery.js></script> <script src=jquery.mobile/jquery.mobile.js></script></head>
<body>
<div data-role=page id=home> <div data-role=header> <h1>Home</h1> </div>
<div data-role=content> <h3> Right justified list</h3> <ul data-role=listview> <li><a><span class=ui-li-aside> Element 1 </span></a></li> <li><a><span class=ui-li-aside> Element 2 </span></a></li> <li><a><span class=ui-li-aside> Element 3 </span></a></li> <li><a><span class=ui-li-aside> Element 4 </span></a></li> <li><a><span class=ui-li-aside> Element 5 </span></a></li> </ul> </div></div>
</body></html>It is also possible, using the ui-li-aside CSS class, to position right only a part of the text in the <li> element. For example, if the list item contains images and texts, it may indicate that a text will be located on the right, while the other will be located on the left.
A text to the right in the list item
<!DOCTYPE html> <html> <head> <meta name=viewport content="user-scalable=no,width=device-width" /> <link rel=stylesheet href=jquery.mobile/jquery.mobile.css /> <script src=jquery.js></script> <script src=jquery.mobile/jquery.mobile.js></script></head>
<body>
<div data-role=page id=home> <div data-role=header> <h1>Home</h1> </div>
<div data-role=content> <h3> Main menu </h3> <ul data-role=listview> <li> <a href=#> <img src=images/html.jpg /> <h1> HTML & CSS</h1> <p> Rufu</p> <span class=ui-li-aside>2 reviews</span> </a> </li> <li> <a href=#> <img src="images/j2ee.jpg" /> <h3>J2EE</h3> <p> Rufu</p> <span class=ui-li-aside>No review</span> </a> </li> <li> <a href=#> <img src="images/jquery.jpg" /> <h3>JQuery & jQuery UI</h3> <p> Rufu</p> <span class=ui-li-aside>5 reviews</span> </a> </li> </ul> </div></div>
</body></html>Note that the <span> elements of ui-li-aside class are positioned a few pixels higher than the other texts. This is the default for ui-li-aside elements.
Using CSS themes
Another way to customize lists is to use CSS themes in them. We know that the CSS themes can be used in the definition of the window, but jQuery Mobile can also use themes in <ul> or <ol> elements (to style the list in its entirety) and in the <li> elements (to style a particular element).
Several themes in a list
The following example uses the "e" theme for the window, the "b" theme for the list and the "a" theme for the second item in the list.
Use multiple themes for lists
<!DOCTYPE html> <html> <head> <meta name=viewport content="user-scalable=no,width=device-width" /> <link rel=stylesheet href=jquery.mobile/jquery.mobile.css /> <script src=jquery.js></script> <script src=jquery.mobile/jquery.mobile.js></script></head>
<body>
<div data-role=page id=home data-theme=e> <div data-role=header> <h1>Home</h1> </div>
<div data-role=content> <h3> Main menu </h3> <ul data-role=listview data-theme=b> <li> <a href=#> <img src=images/html.jpg /> <h1> HTML & CSS</h1> <p> Rufu</p> <span class=ui-li-aside>2 reviews</span> </a> </li> <li data-theme=a> <a href=#> <img src="images/j2ee.jpg" /> <h3>J2EE</h3> <p> Rufu</p> <span class=ui-li-aside>No review</span> </a> </li> <li> <a href=#> <img src="images/jquery.jpg" /> <h3>JQuery & jQuery UI</h3> <p> Rufu</p> <span class=ui-li-aside>5 reviews</span> </a> </li> </ul> </div></div>
</body></html>Customize the separators in lists
The separators between the elements included in a list (using the data-role="list-divider" attribute associated with the <li> element) can be styled with the data-dividertheme attribute valued the desired theme . This attribute is set to the <ul> or <ol> representative or the list in its entirety. All separators in the list will have the theme indicated in this attribute.In the following example, we display two lists using a theme for each of the separators included in them.
Customize separators in lists
<!DOCTYPE html> <html> <head> <meta name=viewport content="user-scalable=no,width=device-width" /> <link rel=stylesheet href=jquery.mobile/jquery.mobile.css /> <script src=jquery.js></script> <script src=jquery.mobile/jquery.mobile.js></script></head>
<body>
<div data-role=page id=home> <div data-role=header> <h1>Home</h1> </div>
<div data-role=content> <h3> List 1</h3> <ul data-role=listview data-dividertheme=a data-inset=true> <li data-role=list-divider>Menu 1</li> <li> Element 1</li> <li> Element 2</li> <li data-role=list-divider>Menu 2</li> <li> Element 3</li> <li> Element 4</li> </ul> <h3> List 2</h3> <ul data-role=listview data-dividertheme=e data-inset=true> <li data-role=list-divider>Menu 3</li> <li> Element 1</li> <li> Element 2</li> <li data-role=list-divider>Menu 4</li> <li> Element 3</li> <li> Element 4</li> </ul> </div></div>
</body></html>Customize the counters displayed in lists
We have seen how to insert a counter in rounded form in the elements of a list, using a <span> element with the ui-li-count CSS class. As for the separators of the elements in a list, these counters can be styled by applying a theme. This is possible by adding the data-counttheme attribute valued the desired theme to the <ul> or <ol> defining the list.
Customize counters lists
<!DOCTYPE html> <html> <head> <meta name=viewport content="user-scalable=no,width=device-width" /> <link rel=stylesheet href=jquery.mobile/jquery.mobile.css /> <script src=jquery.js></script> <script src=jquery.mobile/jquery.mobile.js></script></head>
<body>
<div data-role=page id=home> <div data-role=header> <h1>Home</h1> </div>
<div data-role=content> <h3> List 1</h3> <ul data-role=listview data-inset=true data-counttheme=a> <li> Element 1 <span class=ui-li-count>5</span></li> <li> Element 2 <span class=ui-li-count>10</span></li> </ul>
<h3> List 2</h3> <ul data-role=listview data-inset=true data-counttheme=e> <li> Element 3 <span class=ui-li-count>1</span></li> <li> Element 4 <span class=ui-li-count>7</span></li> </ul> </div></div></body></html>We have defined two lists using counters. Each of these lists uses a different theme to display its counter.
Posted on Utopian.io - Rewarding Open Source Contributors
Your contribution cannot be approved because it does not follow the Utopian Rules.
Explanation:
You can contact us on Discord.
[utopian-moderator]