New York State Department of Labor User Experience (UX) Guide

Implementation

As of v.0.3.1 the DataTables Library is included as part of the User Experience Framework's standard library. There are no scripts to import, as User Experience already includes the library.

Using the predefined function hook, give the target table a class of jQDataTables, to provide the proper CSS class hooks to the predefined DataTables script.

<table id="mySampleTableID" class="data-table jQDataTables" >			
	<caption>My Sample Data Table</caption>
	... table elements ...
<table>

Please see the data table layout documentation on adjusting column widths.

Table Structure

In order for the DataTables Plugin to work correctly, the HTML Table should be constructed properly, making use of <thead> and <th> for column headers, and <tbody> to designate table's content area.

<table id="mySampleTableID" 
	class="data-table jQDataTables" >			
	<caption>My Sample Data Table</caption>
	<thead>
		<tr>
			<th>Version</th>
			<th>Name</th>
			<th>Release Date</th>
			<th>Note</th>
		</tr>
	</thead>
	<tbody>
		<tr>
			<td>v.0.1.0</td>
			<td>-</td>
			<td>?</td>
			<td></td>
		</tr>
		...
	</tbody>
</table>				

JSF Compatibility

Client-side DataTables plugin is compatible with JSF. To use the plugin with JSF data tables, give the JSF data table the CSS class hook.

	<hx:dataTableEx id="myTableID" ...
		styleClass="data-table jQDataTables" ... >
		... my data ...
	</hx:dataTableEx>

When using Client-side DataTables plugin with JSF data tables, it is recommended to apply sorting either by only using the JSF's implementation or only using the plugin's sorting function.

Alternating row colors (row-striping) will be done via the plugin, there's no need to define rowClasses attribute when using an hx:dataTable with Client-side Data Tables plugin.

Default Usage

Assuming that the DataTable is constructed with semantic HTML, and properly formatted, and the class is correctly applied for the JavaScripts to hook onto, the Table will function as the example listed above; with the Search function enabled, and paging and sorting implemented.

Pre-sorting

The default implementation provided by the User Experience Framework does not pre-sort any of the columns. A developer can specify sorting that happens at page load with the follow JavaScript that taps into the DataTables functions. JavaScripts should go into the scripts section within the template near the bottom of the page.

<script>	
$(document).ready(function() { // jQuery
...
	var oTable = $('#My-Table-ID').dataTable( { 
		"bRetrieve" : true
	});	
	oTable.fnSort([ [0,'asc'], [1,'desc'] ] );
...
});
</script>

In the above script, calling function .dataTable({}) with parameter "bRetrieve" : true will retrieve the DataTables Object, in this case it is set it to the variable oTable. This will allow the DataTables function .fnSort() to be called from the DataTables variable.

The function .fnSort() accepts an input of an array. In the above script, we are sorting by the first column (column 0), in asc (Ascending) order; then then second column (column 1), in desc(Descending) order.

Please refer to the DataTables Documentation for further details on how to specify the sorting parameter.
http://datatables.net

Expandable Row Data

Sometimes there are not enough page real-estate available to display all the data in a table. The User Experience Framework has implemented the expandable row functions based on the examples given on the Data Tables Website. This function has been simplified for ease of implementation. It can be achieved by following the below examples.

For the target data to be hidden in an expandable row, structure the HTML like the following for the target <td>.

Use an un-ordered list (<ul>), and the correct classes to the respective elements:

• ux-jQDT-row-expandable on the list-item (<li>),
• ux-jQDT-row-expand-trigger on the anchor (<a>), and
• ux-jQDT-row-expand-content on the div that contains the content to be expanded.

<td>
	<ul>
		<li class="ux-jQDT-row-expandable">
			<a href="#" class="ux-jQDT-row-expand-trigger">Click me Text</a>
			<div class="ux-jQDT-row-expand-content">
				This stuff here is hidden until expanded.	
			</div>
		</li>
	</ul>
</td>

See live example at CSS Utility Classes page.

If the html is structured correctly, the predefined scripts will insert the expandable icon and hide the div immediately following the anchor trigger class when the page is loaded. The expanded row will remain open when the table is sorted by the Client-side Data Tables sort functions. The above code is required for each table cell that contains an expandable.

It is recommended that the expandable content is used only once per table cell. If there are multiple columns of data to expand, consider grouping them together in a logical matter or create new columns.

If JavaScript is not enabled, the expandable will not hide the data or render any of it's functions, since the Client-side Data Tables functions cannot be executed in the first place.

Customizing

Going Beyond the Defaults

There might be a time when the predefined default declaration of DataTables provide too much, or too little function than the application's requirements are needed/requested. In such a case, a developer can declare their own DataTables implementation to suit their application's needs. The corresponding JavaScripts should go into the scripts section.

DataTables has a great deal of customization available. Please refer to the DataTables Documentation for the full feature details.
http://datatables.net

If declaring a customized DataTable hook, please do remember to use the parameter "bJQueryUI": true, so that the custom declared DataTable will hook onto the predefined ThemeRoller CSS, provided by the User Experience Framework.

<table class="data-table myExampleTableClass" ... >
	... my data goes here ...
</table>

<script>
$(document).ready(function() {
...
	$('.myExampleTableClass').dataTable( {
		... custom paramters ...
		"bJQueryUI": true
	} );
...
});
</script>