Using the XNAT JavaScript Library API (JLAPI)

Utility Methods

There are some useful utility methods in the JLAPI that can help with things like making sure URLs have the proper root context and the proper query string or url hash values. There are also a very easy-to-implement form validation and AJAX submission methods.

XNAT.url.*

UI Widgets

There are a number of JavaScript functions built into XNAT to simplify and standardize common UI elements and calls to the back-end to retrieve data and even automatically populate form values from REST calls to /xapi or /data urls.

The basic pattern for invoking and rendering a JLAPI widget looks like this:

// initialize and save widget instance to a variable ('.init()' method is not always required)
var myWidget = XNAT.ui.widgetName.init({
	url: '/data/path/item',
	id: 'my-widgets-unique-id',
	// the 'element' property attaches DOM properties and attributes
	// directly to the main spawned element
	element: {
		title: 'This is a sample widget config',
		data: { foo: 'bar' }
	}
});
 
// render the widget to the page into an existing element
myWidget.render(document.getElementById('my-widget-container'));
 
// alternatively, you can return the outermost DOM element created by the widget
var myWidgetOuterElement = myWidget.get();
 

Each widget has its own unique configuration properties, though there are many properties which are common among all widgets.

Some UI elements that can be spawned and populated with just a few configuration settings:

Widget Types:

XNAT.dataTable()

A standard XNAT data table can be rendered to the page using existing data, for example data that you may have already retrieved via REST or is available in a globally-accessible (namespaced) variable. You can also pass in a 'url' property to let the JLAPI library handle data retrieval and populate the table automatically. The configuration object passed to the dataTable method is the same as the DataTable Spawner Widget, with some extra advantages, like being able to use custom JavaScript to transform cell data before rendering, or using a variable for your dataTable instance for easier manipulation through interactions with the UI.

Easy Config:

// example data as a 2-D array
var dataExample1 = [
	['A', 'B', 'C'],
	[1, 2, 3]
];
 
// initialize and save this XNAT.dataTable instance to a variable
var myTable = XNAT.ui.dataTable(dataExample1, {
	table: {
		title: 'My Table'
	}
});