Freeform Spawner Elements

Whenever possible, it's recommended to use a pre-defined XNAT ui widget and provide values for the required properties to render the widget elements and populate with data (if necessary). Of course, there will be situations when you need UI elements that require more advanced functionality or layout than what a 'canned' XNAT widget can provide, and that's where "Freeform" Spawner element configs can be useful.

A "Freeform" or "Ad-hoc" Spawner element is created using a custom Spawner config object that uses a tag name and properties to render UI elements using the Spawner engine. Creating a Spawner element in this way bypasses the library of available XNAT UI widgets and allows creation of elements that may be very simple and not need to use a widget function, or they may be too complicated and require advanced configuration not available in standard widgets. Using freeform elements enables easy customization of UI elements that are defined in YAML files - for use in the Site Admin UI or anywhere Spawner elements are used.

Below are some examples of freeform Spawner element configs:

Basic Paragraph

As you can see below, CSS selector syntax can be used to add id and class attributes to freeform elements. The main caveat being that the id must be specified first (you can add as many className values as you want, separated by periods). Additional attributes and properties can be added in the tag property as a pipe-separated list (after the id and classes, if used). If the element below was set up in this way, the tag property would be: p#quick-fox.example.dog|title=Filler

Element Config (YAML)

CODE

exampleParagraph:
    tag: "p#quick-fox.example.dog"
    element:
        title: Filler
    content: The <a href="http://quick-brown-fox.com">quick brown fox</a> jumped over the <b>lazy</b> dog.

Generates:

HTML Output

XML

<p id="quick-fox" class="example dog" title="Filler">
    The <a href="http://quick-brown-fox.com">quick brown fox</a> jumped over the <b>lazy</b> dog.
</p>

You may be asking yourself, "What's the point of this? Why can't I just write the HTML?" Well, technically you can, but separating properties as shown in the config YAML above makes editing easier and potentially less problematic; it may also make it easier to programmatically generate element config properties on-the-fly with JavaScript.

Inline Script Element

Element Config (YAML)

CODE

inlineScript:
	tag: script
	content: console.log('inline script executed')

Generates:

HTML Output

XML

<script>console.log('inline script executed')</script>

Linked Script Element

It's super easy to pull in a JavaScript file to add advanced functionality that's beyond the capability of the Spawner service and script. If the src value starts with a "/", the server context will be added to the beginning (in the case that the XNAT instance is not running as the ROOT webapp). The pipe character can be used to separate attributes and properties for the generated element.

Element Config (YAML)

CODE

linkedScript:
	tag: script|src=/scripts/xnat/app/complicatedStuff.js

Generates:

HTML Output

XML

<script src="/scripts/xnat/app/complicatedStuff.js"></script>

Input Element

The input element config shown below demonstrates adding a boolean attribute (readonly) to an element and syntax for dynamically retrieving or generating its value.

Element Config (YAML)

CODE

numberInput:
	tag: "input#numbers.example|type=number|readonly"
	element:
		value: "(( 4*10+2 ))"  # string will be passed to JavaScript eval() function - USE CAREFULLY AND SPARINGLY

Generates:

HTML Output

XML

<input id="numbers" class="example" type="number" readonly value="42">

Raw HTML

If desired, raw HTML can be used to render a Spawner 'element' (but it's not really an element since Spawner is just inserting the HTML string into the page).

Element Config (YAML)

CODE

messageBox:
	html: >
		<div class="message">The way I see it, every life is a pile of good things and bad things... hey... 
		the good things don't always soften the bad things; but vice-versa the bad things don't necessarily 
		spoil the good things and make them unimportant.</div>

Generates:

HTML Output

XML

<div class="message">The way I see it, every life is a pile of good things and bad things... hey... the good things don't always soften the bad things; but vice-versa the bad things don't necessarily spoil the good things and make them unimportant.</div>