New: -button collection button type now has a collectionTitle that can be used to show a title at the top of a collection. This can be useful for use with multi-level collections to ensure the end user knows what the collection refers to.

Author: Allan Jardine

css/common.scss

@@ -25,3 +25,9 @@ div.dt-button-info {
 		padding: 1em;
 	}
 }
+
+div.dt-button-collection-title {
+	text-align: center;
+	padding: 0.3em 0 0.5em;
+	font-size: 0.9em;
+}

docs/button/collection.xml

@@ -66,6 +66,10 @@
 	<option type="boolean" name="dropup" default="false">
 		When `true`, the dropdown collection always drops up. When `false`, the collection drops down or up depending on the available overflow.
 	</option>
+	
+	<option type="string" name="collectionTitle" default="" since="1.5.4">
+		A text string to show at the top of a collection. This can be useful for multi-level collections to ensure the end user knows what the current menu refers to.
+	</option>
 
 
 	<example title="DataTables initialisation: Create an export collection"><![CDATA[

examples/initialisation/collections-sub.xml

@@ -25,7 +25,10 @@ $(document).ready(function() {
 							dt.column( -1 ).visible( ! dt.column( -1 ).visible() );
 						}
 					},
-					'colvis'
+					{
+						collectionTitle: 'Visibility control',
+						extend: 'colvis'
+					}
 				]
 			}
 		]

js/dataTables.buttons.js

@@ -489,7 +489,7 @@ $.extend( Buttons.prototype, {
 				var collectionDom = this.c.dom.collection;
 				built.collection = $('<'+collectionDom.tag+'/>')
 					.addClass( collectionDom.className )
-					.attr( 'role', 'menu') ;
+					.attr( 'role', 'menu' ) ;
 				built.conf._collection = built.collection;
 
 				this._expandButton( built.buttons, built.conf.buttons, true, attachPoint );
@@ -1193,12 +1193,14 @@ $.extend( _dtButtons, {
 				insertPoint = document.body.lastChild;
 			}
 
+			config._collection.find('.dt-button-collection-title').remove();
+			config._collection.prepend('<div class="dt-button-collection-title">'+config.collectionTitle+'</div>');
+
 			config._collection
 				.addClass( config.collectionLayout )
 				.css( 'display', 'none' )
 				.insertAfter( insertPoint )
 				.fadeIn( config.fade );
-			
 
 			var position = config._collection.css( 'position' );
 
@@ -1308,6 +1310,7 @@ $.extend( _dtButtons, {
 		},
 		background: true,
 		collectionLayout: '',
+		collectionTitle: '',
 		backgroundClassName: 'dt-button-background',
 		rightAlignClassName: 'dt-button-right',
 		autoClose: false,