Listview: Review refresh() method

  1. Fix signature of public refresh() method

  2. Move sparing _refresh() decision to backcompat

     The decision is delegated to extension points (one for the list item and
     one the anchor(s) it may contain) which are predicates that always return
     true if the backcompat extension is absent, indicating for every item that
     it is to be processed.

     When the backcompat extension is present, the extension points contain the
     class-examining regex-based decision of previous versions.

  3. Add method updateItems()

     In _refresh() we still need to retrieve all list items, even when we get a
     list of items from updateItems(), because the followings require global
     knowledge:

       - Which items have been removed since last time, so we can untrack them

       - Which is the first resp. last item for use with addFirstLastClasses()

Closes gh-8489
Fixes gh-8334

Author: Gabriel Schulhof

js/widgets/listview.backcompat.js

@@ -32,12 +32,22 @@
 } )( function( $ ) {
 
 if ( $.mobileBackcompat !== false ) {
+	var listviewItemClassRegex = /\bui-listview-item-static\b|\bui-listview-item-divider\b/;
+	var buttonClassRegex = /\bui-button\b/;
+
 	$.widget( "mobile.listview", $.mobile.listview, {
 		options: {
 			corners: true,
 			shadow: true
 		},
-		classProp: "ui-listview-inset"
+		classProp: "ui-listview-inset",
+		_processListItem: function( item ) {
+			return !listviewItemClassRegex.test( item[ 0 ].className );
+		},
+
+		_processListItemAnchor: function( a ) {
+			return !buttonClassRegex.test( a[ 0 ].className );
+		}
 	} );
 	$.widget( "mobile.listview", $.mobile.listview, $.mobile.widget.backcompat );
 }

js/widgets/listview.js

@@ -43,9 +43,7 @@ function addItemToDictionary( itemClassDict, element, key, extra ) {
 }
 
 var getAttribute = $.mobile.getAttribute,
-	countBubbleClassRegex = /\bui-listview-item-count-bubble\b/,
-	listviewItemClassRegex = /\bui-listview-item-static\b|\bui-listview-item-divider\b/,
-	buttonClassRegex = /\bui-button\b/;
+	countBubbleClassRegex = /\bui-listview-item-count-bubble\b/;
 
 function filterBubbleSpan() {
 	var child, parentNode,
@@ -94,7 +92,7 @@ return $.widget( "mobile.listview", $.extend( {
 		if ( this.options.inset ) {
 			this._addClass( "ui-listview-inset" );
 		}
-		this.refresh( true );
+		this._refresh( true );
 	},
 
 	// We only handle the theme option through the theme extension. Theme options concerning list
@@ -131,12 +129,28 @@ return $.widget( "mobile.listview", $.extend( {
 	_beforeListviewRefresh: $.noop,
 	_afterListviewRefresh: $.noop,
 
-	refresh: function( create ) {
+	updateItems: function( items ) {
+		this._refresh( false, items );
+	},
+
+	refresh: function() {
+		this._refresh();
+	},
+
+	_processListItem: function( /* item */ ) {
+		return true;
+	},
+
+	_processListItemAnchor: function( /* a */ ) {
+		return true;
+	},
+
+	_refresh: function( create, items ) {
 		var buttonClass, pos, numli, item, itemClass, itemExtraClass, itemTheme, itemIcon, icon, a,
 			isDivider, startCount, newStartCount, value, last, splittheme, splitThemeClass, li, ol,
 			altButtonClass, dividerTheme, start, itemClassDict, dictionaryKey, span, spliticon,
+			allItems, newSpan,
 			currentOptions = this.options,
-			createEnhanced = create && this.options.enhanced,
 			list = this.element;
 
 		ol = !!$.nodeName( list[ 0 ], "ol" );
@@ -151,20 +165,23 @@ return $.widget( "mobile.listview", $.extend( {
 
 		this._beforeListviewRefresh();
 
-		li = this._getChildrenByTagName( list[ 0 ], "li", "LI" );
+		// We need all items even if a set was passed in - we just won't iterate over them in the
+		// main refresh loop.
+		allItems = this._getChildrenByTagName( list[ 0 ], "li", "LI" );
+		li = items || allItems;
 
 		for ( pos = 0, numli = li.length; pos < numli; pos++ ) {
 			item = li.eq( pos );
 			itemClass = "ui-listview-item";
 			itemExtraClass = undefined;
 
-			if ( create || !listviewItemClassRegex.test( item[ 0 ].className ) ) {
+			if ( create || this._processListItem( item ) ) {
 				a = this._getChildrenByTagName( item[ 0 ], "a", "A" );
 				isDivider = ( getAttribute( item[ 0 ], "role" ) === "list-divider" );
 				value = item.attr( "value" );
 				itemTheme = getAttribute( item[ 0 ], "theme" );
 
-				if ( a.length && ( ( !buttonClassRegex.test( a[ 0 ].className ) && !isDivider ) ||
+				if ( a.length && ( ( this._processListItemAnchor( a ) && !isDivider ) ||
 						create ) ) {
 					itemIcon = getAttribute( item[ 0 ], "icon" );
 					icon = ( itemIcon === false ) ? false : ( itemIcon || currentOptions.icon );
@@ -176,7 +193,7 @@ return $.widget( "mobile.listview", $.extend( {
 					}
 
 					if ( a.length > 1 ) {
-						itemClass = "ui-listview-item-has-alternate";
+						itemClass += " ui-listview-item-has-alternate";
 
 						last = a.last();
 						splittheme = getAttribute( last[ 0 ], "theme" ) ||
@@ -186,25 +203,38 @@ return $.widget( "mobile.listview", $.extend( {
 							getAttribute( item[ 0 ], "icon" ) || currentOptions.splitIcon;
 						altButtonClass = "ui-button ui-button-icon-only" + splitThemeClass;
 
-						span = createEnhanced ? last.children( ".ui-listview-item-split-icon" ) :
-							$( "<span>" );
+						newSpan = false;
+						span = last.children( ".ui-listview-item-split-icon" );
+						if ( !span.length ) {
+							span = $( "<span>" );
+							newSpan = true;
+						}
+
 						addItemToDictionary( itemClassDict, span[ 0 ],
 							"ui-listview-item-split-icon", "ui-icon ui-icon-" + spliticon );
 						addItemToDictionary( itemClassDict, last[ 0 ],
 							"ui-listview-item-split-button", altButtonClass );
 						last.attr( "title", $.trim( last.getEncodedText() ) );
-						if ( !createEnhanced ) {
+
+						if ( newSpan ) {
 							last.empty().prepend( span );
 						}
 
 						// Reduce to the first anchor, because only the first gets the buttonClass
 						a = a.first();
 					} else if ( icon ) {
-						span = createEnhanced ? a.children( ".ui-listview-item-icon" ) :
-							$( "<span>" );
+
+						newSpan = false;
+						span = a.children( ".ui-listview-item-icon" );
+						if ( !span.length ) {
+							span = $( "<span>" );
+							newSpan = true;
+						}
+
 						addItemToDictionary( itemClassDict, span[ 0 ], "ui-listview-item-icon",
 							"ui-icon ui-icon-" + icon + " ui-widget-icon-floatend" );
-						if ( !createEnhanced ) {
+
+						if ( newSpan ) {
 							a.prepend( span );
 						}
 					}
@@ -216,12 +246,12 @@ return $.widget( "mobile.listview", $.extend( {
 					dividerTheme = ( getAttribute( item[ 0 ], "theme" ) ||
 						currentOptions.dividerTheme || currentOptions.theme );
 
-					itemClass = "ui-listview-item-divider";
+					itemClass += " ui-listview-item-divider";
 					itemExtraClass = "ui-bar-" + ( dividerTheme ? dividerTheme : "inherit" );
 
 					item.attr( "role", "heading" );
 				} else if ( a.length <= 0 ) {
-					itemClass = "ui-listview-item-static";
+					itemClass += " ui-listview-item-static";
 					itemExtraClass = "ui-body-" + ( itemTheme ? itemTheme : "inherit" );
 				}
 				if ( ol && value ) {
@@ -259,7 +289,9 @@ return $.widget( "mobile.listview", $.extend( {
 
 		this._afterListviewRefresh();
 
-		this._addFirstLastClasses( li, this._getVisibles( li, create ), create );
+		// NOTE: Using the extension addFirstLastClasses is deprecated as of 1.5.0 and this and the
+		// extension itself will be removed in 1.6.0.
+		this._addFirstLastClasses( allItems, this._getVisibles( allItems, create ), create );
 
 		// Untrack removed items
 		if ( this._oldListItems ) {
@@ -269,7 +301,7 @@ return $.widget( "mobile.listview", $.extend( {
 				} ),
 				"ui-listview-item ui-listview-item-static ui-listview-item-has-count " +
 				"ui-listview-item-has-alternate ui-listview-item-divider" );
-			this._oldListItems = li;
+			this._oldListItems = allItems;
 		}
 	}
 }, $.mobile.behaviors.addFirstLastClasses ) );

tests/integration/listview/backcompat-tests.html

@@ -34,6 +34,11 @@
 				<li>Item 2</li>
 			</ul>
 		</div>
+
+		<ul id="sparing-check" data-nstest-role="listview">
+			<li id="sparing-check-first-item">Item 1</li>
+			<li id="sparing-check-second-item">Item 2</li>
+		</ul>
 	</div>
 </body>
 </html>

tests/integration/listview/backcompat_core.js

@@ -1,7 +1,8 @@
 define( [
 	"qunit",
-	"jquery"
-	], function( QUnit, $ ) {
+	"jquery",
+	"../tests/integration/listview/sparing-setup-teardown"
+	], function( QUnit, $, sparingSetupTeardown ) {
 
 var helper = $.testHelper;
 
@@ -106,4 +107,17 @@ QUnit.test( "Turning on class ui-shadow", function( assert ) {
 		"Option shadow is true whenever ui-shadow is present in ui-listview-inset" );
 } );
 
+QUnit.module( "Sparingness of refresh()", sparingSetupTeardown );
+
+QUnit.test( "refresh()", function( assert ) {
+	assert.expect( 2 );
+
+	this.listview.refresh();
+
+	assert.strictEqual( this.calls[ 1 ][ 0 ].length, 1,
+		"One element was passed to _addClass()" );
+	assert.deepEqual( this.calls[ 1 ][ 0 ].get( 0 ), this.newItem[ 0 ],
+		"The single item in the call is as expected" );
+} );
+
 } );

tests/integration/listview/index.html

@@ -180,6 +180,21 @@
 					</a>
 				</li>
 			</ul>
+
+			<ul data-ui-role="listview" id="icon-refresh">
+				<li data-ui-icon="home"><a href="#">Home</a></li>
+				<li data-ui-icon="delete"><a href="#">Delete</a></li>
+			</ul>
+
+			<ul data-ui-role="listview" id="icon-update-items">
+				<li data-ui-icon="home"><a href="#">Home</a></li>
+				<li data-ui-icon="delete"><a href="#">Delete</a></li>
+			</ul>
+
+			<ul data-ui-role="listview" id="sparing-check">
+				<li id="sparing-check-first-item">Item 1</li>
+				<li id="sparing-check-second-item">Item 2</li>
+			</ul>
 		</div>
 	</div>
 

tests/integration/listview/listview_core.js

@@ -5,8 +5,9 @@
 // TODO split out into separate test files
 define( [
 	"qunit",
-	"jquery"
-	], function( QUnit, $ ) {
+	"jquery",
+	"../tests/integration/listview/sparing-setup-teardown"
+	], function( QUnit, $, sparingSetupTeardown ) {
 
 QUnit.module( "Basic Linked list" );
 
@@ -458,4 +459,58 @@ QUnit.test( "basic pre-enhanced listview", function( assert ) {
 		"Listview refresh() enhances new items" );
 } );
 
+QUnit.module( "Sparingness of refresh() and updateItems()", sparingSetupTeardown );
+
+QUnit.test( "refresh()", function( assert ) {
+	assert.expect( 5 );
+
+	this.listview.refresh();
+
+	assert.strictEqual( this.calls[ 0 ][ 0 ].length, 3,
+		"Three elements were passed to _addClass()" );
+	assert.strictEqual( this.calls[ 0 ][ 1 ], "ui-listview-item ui-listview-item-static",
+		"Class ui-listview-item-static was assigned" );
+	assert.strictEqual( this.calls[ 0 ][ 0 ].first().attr( "id" ), "sparing-check-first-item",
+		"The first item in the call is as expected" );
+	assert.deepEqual( this.calls[ 0 ][ 0 ].get( 1 ), this.newItem[ 0 ],
+		"The second item in the call is as expected" );
+	assert.strictEqual( this.calls[ 0 ][ 0 ].last().attr( "id" ), "sparing-check-second-item",
+		"The last item in the call is as expected" );
+} );
+
+QUnit.test( "updateItems()", function( assert ) {
+	assert.expect( 2 );
+
+	this.listview.updateItems( this.newItem );
+
+	assert.strictEqual( this.calls[ 0 ][ 0 ].length, 1,
+		"One element was passed to _addClass()" );
+	assert.deepEqual( this.calls[ 0 ][ 0 ].get( 0 ), this.newItem[ 0 ],
+		"The single item in the call is as expected" );
+} );
+
+QUnit.module( "Dynamic icon update" );
+
+QUnit.test( "via refresh()", function( assert ) {
+	var listview = $( "#icon-refresh" );
+
+	listview.children().first().attr( "data-ui-icon", "back" );
+	listview.listview( "refresh" );
+
+	assert.hasClasses( listview.children().first().find( ".ui-listview-item-icon" ),
+		"ui-icon-back",
+		"Listview item icon is as expected" );
+} );
+
+QUnit.test( "via updateItems()", function( assert ) {
+	var listview = $( "#icon-update-items" );
+
+	listview.children().first().attr( "data-ui-icon", "back" );
+	listview.listview( "updateItems", listview.children().first() );
+
+	assert.hasClasses( listview.children().first().find( ".ui-listview-item-icon" ),
+		"ui-icon-back",
+		"Listview item icon is as expected" );
+} );
+
 } );

tests/integration/listview/sparing-setup-teardown.js

@@ -0,0 +1,24 @@
+define( [ "jquery" ], function( $ ) {
+
+return {
+	setup: function() {
+		var that = this;
+
+		this.template = $( "#sparing-check" ).clone();
+		this.listview = $( "#sparing-check" ).listview().listview( "instance" );
+		this.newItem = $( "<li>Something</li>" ).insertAfter( "#sparing-check-first-item" );
+		this.calls = [];
+		this._addClass = $.mobile.listview.prototype._addClass;
+
+		$.mobile.listview.prototype._addClass = function() {
+			that.calls.push( arguments );
+			return that._addClass.apply( this, arguments );
+		};
+	},
+	teardown: function() {
+		$( "#sparing-check" ).before( this.template ).remove();
+		$.mobile.listview.prototype._addClass = this._addClass;
+	}
+};
+
+} );