New options maxItemsToShowWhenResponsiveThresholdSurpassed and showTa…

…ilWhenNotEnoughItemsForEvenOneRow

README.md

@@ -6,7 +6,7 @@ A jQuery plugin by Tin.cat that builds responsive mosaics of images or any other
 Works wonderfully with images by creating a visually ordered and pleasant mosaic (much like mosaics on Flickr, 500px and Google+) without gaps between elements, but at the same time respecting aspect ratios. Reacts to window resizes and adapts responsively to any screen size.
 
 ### Version history
-* **v0.15.2** Added maxRows option for those situations where you need fine control on the maximum number of rows of your mosaic.
+* **v0.15.2** Added maxRows option for those situations where you need fine control on the maximum number of rows of your mosaic. Added advanced options maxItemsToShowWhenResponsiveThresholdSurpassed and showTailWhenNotEnoughItemsForEvenOneRow for even more fine-grained control of your mosaic.
 * **v0.15** Added the ability to pass parameters as html data-* attributes. Solved floating point width bug for compatibility with jQuery versions < 3. Thanks to [@BenTalagan](https://github.com/BenTalagan).
 * **v0.14** New maxRowHeightPolicy 'tail' that renders items respecting their aspect ratio without surpassing the specified maxRowHeight, resulting in a last row that might not completely fit the screen horizontally, suggested by [@borekl](https://github.com/borekl) and [@nzjrs](https://github.com/nzjrs).
 * **v0.13** New outerMargin and innerGap parameters.

examples/index.php

@@ -55,20 +55,20 @@
 			<h1>Version history</h1>
 			<ul class=\"fancy\">
 				<li>
-					<b>v0.152</b><br>
-					Added maxRows option for those situations where you need fine control on the maximum number of rows of your mosaic.
+					<b>v0.15.2</b><br>
+					Added <a href=\"#maxRows\">maxRows</a> option for those situations where you need fine control on the maximum number of rows of your mosaic. Added advanced options <a href=\"#maxItemsToShowWhenResponsiveThresholdSurpassed\">maxItemsToShowWhenResponsiveThresholdSurpassed</a> and <a href=\"#showTailWhenNotEnoughItemsForEvenOneRow\">showTailWhenNotEnoughItemsForEvenOneRow</a> for even more fine-grained control of your mosaic.
 				</li>
 				<li>
 					<b>v0.15</b><br>
 					Added the ability to pass parameters as html data-* attributes. Solved floating point width bug for compatibility with jQuery versions < 3. Thanks to <a href=\"https://github.com/BenTalagan\" target=\"credit\">@BenTalagan</a>
 				</li>
 				<li>
 					<b>v0.14</b><br>
-					New maxRowHeightPolicy 'tail' that renders items respecting their aspect ratio without surpassing the specified maxRowHeight, resulting in a last row that might not completely fit the screen horizontally, suggested by <a href=\"https://github.com/borekl\" target=\"credit\">@borekl</a> and <a href=\"https://github.com/nzjrs\" target=\"credit\">@nzjrs</a>
+					New <a href=\"#maxRowHeightPolicy\">maxRowHeightPolicy</a> 'tail' that renders items respecting their aspect ratio without surpassing the specified maxRowHeight, resulting in a last row that might not completely fit the screen horizontally, suggested by <a href=\"https://github.com/borekl\" target=\"credit\">@borekl</a> and <a href=\"https://github.com/nzjrs\" target=\"credit\">@nzjrs</a>
 				</li>
 				<li>
 					<b>v0.13</b><br>
-					New outerMargin and innerGap parameters.
+					New <a href=\"#outerMargin\">outerMargin</a> and <a href=\"#innerGap\">innerGap</a> parameters.
 				</li>
 			</ul>
 		</div></div>
@@ -131,26 +131,31 @@
 			<p>You can optionally specify the following options when calling the plugin to customize the mosaic:</p>
 			<ul class=\"options\">
 				<li>
+					<a name=\"maxRowHeight\"></a>
 					<div class=\"name\">maxRowHeight</div>
 					<div class=\"description\">The maximum desired height of rows</div>
 					<div class=\"default\">400</div>
 				</li>
 				<li>
+					<a name=\"refitOnResize\"></a>
 					<div class=\"name\">refitOnResize</div>
 					<div class=\"description\">Whether to rebuild the mosaic when the window is resized or not</div>
 					<div class=\"default\">true</div>
 				</li>
 				<li>
+					<a name=\"refitOnResizeDelay\"></a>
 					<div class=\"name\">refitOnResizeDelay</div>
 					<div class=\"description\">Milliseconds to wait after a resize event to refit the mosaic. Useful when creating huge mosaics that can take some CPU time on the user's browser. Leave it to false to refit the mosaic in realtime</div>
 					<div class=\"default\">false</div>
 				</li>
 				<li>
+					<a name=\"defaultAspectRatio\"></a>
 					<div class=\"name\">defaultAspectRatio</div>
 					<div class=\"description\">The aspect ratio to use when none has been specified, or can't be calculated</div>
 					<div class=\"default\">1</div>
 				</li>
 				<li>
+					<a name=\"maxRowHeightPolicy\"></a>
 					<div class=\"name\">maxRowHeightPolicy</div>
 					<div class=\"description\">Sometimes some of the remaining items cannot be fitted on a row without surpassing the maxRowHeight. For those cases, choose one of the available settings for maxRowHeightPolicy:
 						<ul>
@@ -163,30 +168,47 @@
 					<div class=\"default\">skip</div>
 				</li>
 				<li>
+					<a name=\"maxRows\"></a>
 					<div class=\"name\">maxRows</div>
 					<div class=\"description\">In some scenarios you might need fine control about the maximum number of rows of the mosaic. If specified, the mosaic won't have more than this number of rows. If responsiveWidthThreshold is specified, maxRows are not considered when the threshold has been reached</div>
 					<div class=\"default\">false</div>
 				</li>
 				<li>
+					<a name=\"highResImagesWidthThreshold\"></a>
 					<div class=\"name\">highResImagesWidthThreshold</div>
 					<div class=\"description\">The item width on which to start using the the provided high resolution image instead of the normal one. High resolution images are specified via the \"data-high-res-image-src\" or \"data-high-res-background-image-url\" html element properties of each item.</div>
 					<div class=\"default\">350</div>
 				</li>
 				<li>
+					<a name=\"outerMargin\"></a>
 					<div class=\"name\">outerMargin</div>
 					<div class=\"description\">A margin size in pixels for the outher edge of the whole mosaic.</div>
 					<div class=\"default\">0</div>
 				</li>
 				<li>
+					<a name=\"innerGap\"></a>
 					<div class=\"name\">innerGap</div>
 					<div class=\"description\">A gap size in pixels to leave a space between elements.</div>
 					<div class=\"default\">0</div>
 				</li>
 				<li>
+					<a name=\"responsiveWidthThreshold\"></a>
 					<div class=\"name\">responsiveWidthThreshold</div>
 					<div class=\"description\">The minimum width for which to keep building the mosaic. If specified, when the width is less than this, the mosaic building logic is not applied, and one item per row is always shown. This might help you avoid resulting item sizes that are too small and might break complex html/css inside them, specially when aiming for great responsive mosaics. When using this, you can also specify a \"data-only-force-height-when-necessary\" html item property with value \"1\" in the specific items you don't want to apply forced aspect ratios when this minimum width threshold is reached.</div>
 					<div class=\"default\">false</div>
 				</li>
+				<li>
+					<a name=\"maxItemsToShowWhenResponsiveThresholdSurpassed\"></a>
+					<div class=\"name\">maxItemsToShowWhenResponsiveThresholdSurpassed</div>
+					<div class=\"description\">If set (and also responsiveWidthThreshold is set), only this amount of items will be shown when the responsiveWidthThreshold is met.</div>
+					<div class=\"default\">false</div>
+				</li>
+				<li>
+					<a name=\"showTailWhenNotEnoughItemsForEvenOneRow\"></a>
+					<div class=\"name\">showTailWhenNotEnoughItemsForEvenOneRow</div>
+					<div class=\"description\">If this is set to true, when there are not enough items to fill even a single row, they will be shown anyway even if they do not complete the row horizontally. If left to false, no mosaic will be shown in such occasions.</div>
+					<div class=\"default\">false</div>
+				</li>
 			</ul>
 			<p>For example:</p>
 			<code class=\"isolated html\">".formatHtml("

jquery.mosaic.css

@@ -1,5 +1,5 @@
 /*
-	 jQuery Mosaic v0.152
+	 jQuery Mosaic v0.15.2
 	 https://github.com/tin-cat/jquery-mosaic
  */
 

jquery.mosaic.js

@@ -1,5 +1,5 @@
 /*
-	 jQuery Mosaic v0.152
+	 jQuery Mosaic v0.15.2
 	 https://github.com/tin-cat/jquery-mosaic
 	 A jquery plugin by Tin.cat to build beautifully arranged and responsive mosaics of html elements maintaining their original aspect ratio. Works wonderfully with images by creating a visually ordered and pleasant mosaic (much like mosaics on Flickr, 500px and Google+) without gaps between elements, but at the same time respecting aspect ratios. Reacts to window resizes and adapts responsively to any screen size. See it working on https://skinography.net
  */
@@ -204,7 +204,14 @@
 
 			if (base.isBelowResponsiveWidthThreshold()) {
 
-				base.getItems().each(function() {
+				var items = base.getItems();
+
+				if (o.maxItemsToShowWhenResponsiveThresholdSurpassed) {
+					$(items).slice(o.maxItemsToShowWhenResponsiveThresholdSurpassed).remove();
+					items = $(items).slice(0, o.maxItemsToShowWhenResponsiveThresholdSurpassed);
+				}
+
+				items.each(function() {
 					var height = base.getItemHeightForGivenWidth(this, baseWidth);
 
 					$(this).width(baseWidth)
@@ -258,8 +265,11 @@
 			}
 
 			// If maxRowHeight has not been met at any point (might happen when specifying short maxRowHeights)
-			if (!isAnyFitted)
+			if (!isAnyFitted) {
+				if (o.showTailWhenNotEnoughItemsForEvenOneRow)
+					o.maxRowHeightPolicy = 'tail';
 				base.fitItems(base.getItems());
+			}
 		}
 
 		base.fitItems = function(items) {
@@ -314,7 +324,9 @@
 		highResImagesWidthThreshold: 350, // The item width on which to start using the the provided high resolution image instead of the normal one. High resolution images are specified via the "data-high-res-image-src" or "data-high-res-background-image-url" html element properties of each item.
 		outerMargin: 0, // A margin size in pixels for the outher edge of the whole mosaic
 		innerGap: 0, // A gap size in pixels to leave a space between elements
-		responsiveWidthThreshold: false // The minimum width for which to keep building the mosaic. If specified, when the width is less than this, the mosaic building logic is not applied, and one item per row is always shown. This might help you avoid resulting item sizes that are too small and might break complex html/css inside them, specially when aiming for great responsive mosaics.
+		responsiveWidthThreshold: false, // The minimum width for which to keep building the mosaic. If specified, when the width is less than this, the mosaic building logic is not applied, and one item per row is always shown. This might help you avoid resulting item sizes that are too small and might break complex html/css inside them, specially when aiming for great responsive mosaics.
+		maxItemsToShowWhenResponsiveThresholdSurpassed: false, // If set (and also responsiveWidthThreshold is set), only this amount of items will be shown when the responsiveWidthThreshold is met
+		showTailWhenNotEnoughItemsForEvenOneRow: false, // If this is set to true, when there are not enough items to fill even a single row, they will be shown anyway even if they do not complete the row horizontally. If left to false, no mosaic will be shown in such occasions.
 	};
 
 	$.fn.Mosaic = function(options, params) {