Using Spawner and the XNAT UI Library

About

The Spawner service works in conjunction with XNAT UI JavaScript functions to dynamically generate UI elements. The Spawner service is inherently "dumb" and only parses YAML files, resolves references within those files, and outputs a JSON blob that can be consumed by the front-end UI library to render page elements – it does not directly generate the HTML that appears on the page. However, the Spawner service is not required to generate UI elements – they can be created directly with the UI library JavaScript functions, as will be shown below.

Terminology

Spawner Service

The Spawner Service is a back-end service that parses YAML files that reside in a special location on the server:

CODE

webapps/your-webapp/WEB-INF/classes/META-INF/xnat/spawner

The service resolves ${variable} references within the files and can return JSON with a GET request to the appropriate URL.

CODE

GET http://your-xnat.com/xapi/spawner/resolve/siteAdmin/root

A GET request made to the above url (on your XNAT server) should return the JSON that's used to render the Site Administration UI. This is just a giant JSON blob, and when parsed with the UI functions, HTML elements will be generated that make up the Site Administration page. The function below is what's used to get elements and render them to the page. The server request and element tree parsing happens behind the scenes and inserts the spawned elements in the '#view-page' element, which is present on the page beforehand.

JS

XNAT.spawner.resolve('siteAdmin/root').ok(function(){ this.render('#view-page') })

Spawner Elements

UI widget configurations defined in Spawner YAML files are referred to as Spawner Elements (or Spawner Configs or element configs). Spawner Elements are not the HTML elements ultimately rendered to the page, but are the YAML/JSON objects used to define them.

UI Widgets

UI widgets – sometimes called Spawner widgets – are the actual rendered HTML elements that appear on the page. They are created with JavaScript functions associated with their 'kind' (widget type) as defined in the element config.