documentation/sorting.html

<div id="midcolumn">
	<h3>Sorting</h3>
	<div id="doccontent">
		<div class="chapter">
			<h5>Sorting with GlazedLists</h5>
			<div class="content">
				<p>In this section we will walk through the <span class="code">SortableGridExample</span> to demonstrate sorting in NatTable. 
				Further on, we will see how to plugin custom comparators.</p>
				
				<p>NatTable uses the <span class="code">SortedList</span> from the GlazedLists project to do the actual sorting. 
				Hence, as a first step, you will have to wrap your List data structure with a <span class="code">SortedList</span> instance. 
				The <span class="code">IDataProvider</span> now uses the sorted list as its data source.</p>
				
				<div class="codeBlock">SortedList sortedList 
	= new SortedList(eventList, null);
IColumnPropertyAccessor columnPropertyAccessor
	= new ReflectiveColumnPropertyAccessor(propertyNames);
bodyDataProvider
	= new ListDataProvider(sortedList, columnPropertyAccessor);</div>
				<p class="subline">Snippet from GlazedListsGridLayer of SortableGridExample</p>
				
				<p>The sorting functionality is added by the <span class="code">SortHeaderLayer</span>. 
				This implies that this layer has to be added to the stack to enable sorting. 
				Since sorting is triggered by the column header this layer will be added to the column header layer stack.</p>
				<div class="codeBlock">columnHeaderLayer 
	= new ColumnHeaderLayer(
		dataLayer, bodyLayerStack, bodyLayerStack.getSelectionLayer());

SortHeaderLayer sortHeaderLayer = new SortHeaderLayer(
					columnHeaderLayer,
					new GlazedListsSortModel(
					sortedList,
						columnPropertyAccessor,
						configRegistry,
						dataLayer),
					false);</div>
                <p class="subline">Snippet from GlazedListsColumnHeaderLayerStack of SortableGridExample</p>
                
                <p>In the above snippet, the <span class="code">SortHeaderLayer</span> takes in a <span class="code">ISortModel</span> 
                (second parameter). This is the GlazedLists specific code to which we delegate the sorting. If you wish to use your 
                custom implementation of a sort algorithm, you can plug in your own <span class="code">ISortModel</span> here.</p>

				<p>Also note that we set 'autoconfigure' (last parameter) to false. This instructs the layer not to use any default 
				setup. We do this in order to enable us to modify the default sort configuration. More on that in a bit. You can set 
				this to <span class="code">true</span> if you are happy with the default settings.</p>
			</div>
		</div>
		
		<div class="chapter">
			<h5>Using custom comparators</h5>
			<div class="content">
				<p>The default comparator treats the objects in the column being sorted as <span class="code">Comparable</span>.</p>

				<p>Custom comparators can be plugged in by registering your comparator as a <span class="code">SortConfigAttributes.SORT_COMPARATOR</span> 
				attribute in the config registry.<br>
				This is a two step process:
					<ol>
						<li>Apply labels to the column header cells</li>
						<li>Register your comparator against those labels</li>
					</ol>
    			</p>
    			<div class="codeBlock">// Add label accumulator
ColumnOverrideLabelAccumulator labelAccumulator 
	= new ColumnOverrideLabelAccumulator(columnHeaderDataLayer);
columnHeaderDataLayer.setConfigLabelAccumulator(labelAccumulator);

// Register labels
labelAccumulator.registerColumnOverrides(
	RowDataListFixture.getColumnIndexOfProperty(RowDataListFixture.RATING_PROP_NAME),
	CUSTOM_COMPARATOR_LABEL);

// Register custom comparator
configRegistry.registerConfigAttribute(SortConfigAttributes.SORT_COMPARATOR,
					getCustomComparator(),
					DisplayMode.NORMAL,
 					CUSTOM_COMPARATOR_LABEL);</div>
			</div>
		</div>
		
		<div class="chapter">
			<h5>Disable sorting on selected columns</h5>
			<div class="content">
				<p>Disabling sorting is very similar to applying custom comparator to a column. The only difference is that you 
				register a <span class="code">NullComparator</span> as your custom comparator. 
				The <span class="code">SortableGridExample</span> demonstrates this.</p>
			</div>
		</div>
		
		<div class="chapter">
			<h5>Customize sort configuration</h5>
			<div class="content">
				<p>The <span class="code">DefaultSortConfiguration</span> object sets up the:
					<ol>
						<li>default sort comparators (uses Comparable.compareTo())</li>
						<li>default sort header cell painters (Arrows of varying shapes)</li>
						<li>default mouse bindings for triggering sorting (Alt + left click, Alt + Shift + left click for additive sort)</li>
					</ol>
					
					<p>By overriding the <span class="code">DefaultSortConfiguration</span> you can customize the settings mentioned above. 
					An example of this is the <span class="code">SingleClickSortConfiguration</span>.</p>
					
					<p>This overrides the default sort configuration and changes the mouse bindings to sort on a single click. 
					Remember to register your new configuration as follows:

    				<div class="codeBlock">sortHeaderLayer.addConfiguration(new SingleClickSortConfiguration());</div>
			</div>
		</div>
		
		<div class="chapter">
			<h5>Sorting without GlazedLists</h5>
			<div class="content">
				<p>It is recommended to use GlazedLists to get full performance benefits on using the NatTable with huge datasets.
				Nevertheless it is possible to enable sorting without using GlazedLists. To do this you have to implement your
				own <span class="code">ISortModel</span> and use it for instantiating the <span class="code">SortHeaderLayer</span>
				instead of using the <span class="code">GlazedListsSortModel</span>.
			</div>
		</div>
	</div>	
</div>