Customizing Listings

XNAT builder scripts automatically generate listings for your root level elements. But these generated listings are often cumbersome. You can customize the listings to reflect a preferable structure. The structure of the listings are driven by XML files that specify which fields comprise the display listing for each data type. These XML files are located in the folder display next to the relevant schema.

There are many specifications which can be made in display documents. The two primary features of the display documents are the DisplayFields and the DisplayVersions:

  • DisplayFields define the fields that can be displayed in a listing.
  • DisplayVersions specify which fields will be visible in specific listing. The most important DisplayVersion is the one labeled 'listing'. This is the DisplayVersion which will determine what columns appear in the default listing on the website (from the Browse section). The DisplayVersion 'listing_csv' is the version of the listing which will be downloaded by the spreadsheet link.

To modify the display document for a particular data type:

  1. Open the display document for the data type you want to change. The display document can be found in the XNAT_HOME/projects/PROJECT/src/schemas/SCHEMA_DIR/display directory.
  2. Remove any unnecessary or unwanted DisplayFieldRefs from the DisplayVersion listing and save the file. 
  3. Update and deploy your XNAT application.
  4. Click the Administer->More Options... menu command.
  5. Click the Refresh Display Documents link. This reloads the display documents, including the file you changed. If your webapp was not running before the change was made, then this step will not be necessary as the changes will be loaded when the webapp starts up.

Your updated listing should now be visible in the web application.

For more information on how the display documents work, and how you can make more complicated customizations, consult the Listing documentation.