Step 4 of 10 Injecting user interface elements

Goal

Add some UI elements to your plugin that will appear in the XNAT interface.

Once you have your own data type in XNAT, you'll immediately want some way to create, display and edit an object of that data type. As with writing the data type, this practical lesson won't focus so much on the contents of these UI elements as on how these elements are integrated with the XNAT application.

The most important thing to know about UI elements in XNAT 1.7–as well as any other type of web content, such as style sheets, graphics files, JavaScript files, and so on–is that everything that you would think of as part of the "web site" goes under a single folder structure:

src/main/resources/META-INF/resources

Anything under this folder is placed in the folder META-INF/resources in the jar file that gets built from your plugin project. META-INF/resources has special meaning in the Servlet 3.0 specification (see section 4.6): anything in this folder in any jar on the application classpath is treated as if it is located at the root of the web application and is fully equivalent with resources in the application itself. That means that any of your web resources in this folder are automatically part of your web application. The XNAT plugin framework takes advantage of this feature to inject UI elements from plugins into the application.

OK, you know how to add resources to the web application, but what can you add and where should it go (knowing that you start at META-INF/resources doesn't tell you what to do to add, for example, a menu command that will let users create an instance of your data type. There are two primary ways to integrate UI elements into XNAT:

• Standard data type pages
• Injection elements

Standard data type pages

There are a number of pages that are automatically generated for data types when you build your plugin project. These take the following form:

• folder/screens/XDATScreen_verb_namespace_dataType.vm

Where:

• folder is one of the template folders from the XNAT folder search hierarchy: templates, module-templates, xnat-templates, xdat-templates, and base-templates. XNAT uses this hierarchy to allow you to override the standard display files by creating files of the same name in different locations in the hierarchy. For example, all generated Velocity templates are placed under the base-templates folder. Most standard XNAT templates are under xnat-templates or xdat-templates. This lets you override any given base or standard template by creating your own version of the file under templates or module-templates (templates is most commonly and widely used, but module-templates is available).
• verb is the action the page lets you perform. The actions for the standard generated pages are edit and report, although there are other supported actions for some data types, including add, delete, download, and manage.
• namespace is the namespace of the data-type schema. In the case of the biosample collection data type, this is workspace.
• dataType is the name of the data type. In the case of the biosample collection data type, this is biosampleCollection.

 So your implementation of the report and edit pages for the biosample collection data type would go in:

• templates/screens/XDATScreen_edit_workshop_biosampleCollection.vm
• templates/screens/XDATScreen_report_workshop_biosampleCollection.vm
  

When you compile your plugin project, you'll see that these files are automatically generated under the base-templates folder. You can use those as a basis to work from or you can download the attached versions of the edit and report pages and just copy them into the appropriate location in your project.

Injection elements

XNAT has many points where it will look in particular locations for templates that will be included directly into the XNAT interface. If you create a template and place it in one of those locations, your template will be picked up by the XNAT UI and displayed as if it were a regular part of the XNAT application.

One of these extension points is the actionsBox folder, which is located in a number of places, but for our needs the one under the xnat_subjectData folder is the most applicable. As you can probably guess from the name, this folder contains items that are added to the actions box that's displayed when you're looking at a subject's page. If you look at this folder in XNAT itself, you'll see that there are already a number of files in this folder, including Delete.vm, ManageFiles.vm, RunScript.vm, and UploadFiles.vm. To add an option to the actions box, then, you can add a file to your plugin project, something like this:

src/main/resources/META-INF/resources/templates/screens/xnat_subjectData/actionsBox/Biosample.vm

The contents of Biosample.vm should look something like this:

<!-- Sequence: 6 -->
<li class="yuimenuitem">
    <A href="$link.setPage('XDATScreen_edit_working_biosampleCollection.vm')">
        <div class="ic">&nbsp;</div><div class="ic_spacer">&nbsp;</div>Add Biosamples
    </A>
</li>

Don't worry too much about the contents of this file. This should take you to the edit page for your biosample collection page where you can create a new instance of the data type.

For this plugin, you can download the attached zip file and extract it into your plugin folder. This adds four files:

All locations in the table above are relative to the src/main/resources/META-INF/resources/templates/screens path.

Completed!

You now have a couple of interface elements that will appear directly in the XNAT user interface.

Go to the next step