User Interface

XNAT 1.6 makes it fairly easy and straightforward to extend the user interface, not just by overriding existing pages or adding new pages, but in many places adding sections to existing pages or tabs to configuration or properties pages. For example, it's really easy to add tabs to the Configuration page in the Administer functions of the XNAT interface:

The source for this simple extension is attached to this page. To get it to appear, all you need to do is place it in the templates/screens/configuration subfolder of your deployed Web application. You can use the default tabs in the configuration dialog as a guide to harnessing the functionality in the configuration dialog. These are located in the xnat-templates/screens/configuration folder of the deployed application or the plugin-resources/webapp/xnat-templates/screens/configuration folder of your xnat_builder installation.

For XNAT 1.6.0 and below, there is no implementation-independent way to associate your settings in a custom configuration tab with settings in XNAT. This requires modifying the code in the SettingsRestlet class to handle custom properties.

In XNAT 1.6.1, the SettingsRestlet is smart enough to save any properties POSTed to it from the configuration screen as site configuration properties. Just add your new properties to the UI layer.

You can specify the tab title and div name of your custom tab by adding HTML comments into your template:

<!-- title: Sample Tab -->
<!-- divName: sampleTab -->

The title can be set to any phrase or name, although you should be careful not to make it too long to prevent "tab creep" (you'll notice that the sample tab above is already on a new row!). The divName is used to reference the HTML <div> that contains the tab display code and is used by the underlying JavaScript to manage the tab. The tab and div name both have the default value of the file name, minus the .vm extension.

But there's more! The Configuration dialog is only one of the many places where the user interface can be extended. Rather than try to document every single one of them, XNAT contains a property setting UI.debug-extension-points that, when set to true, causes all extension points to be highlighted:


Within each highlighted area, the path where you need to put your templates is indicated. So, in this case, to add a new item to the top-bar menu, you can put a template in the templates/screens/topBar folder.

To set the UI.debug-extension-points property to true, you need to override the default setting for this property. See Custom Properties and Overriding Default Properties for more information.